UpStream API - WordPress Plugin

Guide to Setting Up and Using UpStream API

UpStream API is not about adding a nice-looking screen to the admin panel. Its real purpose is to connect UpStream with external systems: client portals, reporting dashboards, internal agency panels, request forms, support services, and custom scripts. In this guide, we will walk through how to approach the add-on installation, which permissions and authentication methods to verify, how to read and update projects through the REST API, where integrations usually break, and how to validate the result safely without risking production data.

Unlike a typical plugin with visual settings, UpStream API is exposed through requests to WordPress REST API routes. That means the administrator's main job is not to "find the button," but to prepare a test environment, a user account with the right capabilities, a clear object map, and a validation checklist. If you do that upfront, the integration becomes predictable: the external service only sees what you intentionally expose, and project updates do not turn into accidental imports of bad data.

This guide is written for site owners, webmasters, and developers who already use UpStream as a project management system or plan to connect external workflows to it. We will not cover purchasing, license registration, or activation workarounds. What follows is practical setup, testing, request examples, limitations, and troubleshooting.

What the API Add-On Actually Gives You for Project Data

UpStream stores projects, tasks, milestones, bugs, files, clients, and discussions inside WordPress. The standard interface works well when a manager handles everything manually in the admin panel or when a client views the public side of a project. The API add-on solves a different problem: it allows an external tool to access UpStream data through REST routes and perform controlled read and update operations.

The official documentation describes routes in the format /wp-json/upstream/v1/<object-url-component>. Instead of abstract "access to everything," the add-on splits data into specific components: projects, milestones, tasks, bugs, files, and clients. This works well for integrations because you can build a clean exchange layer: one part of the system creates tasks, another updates statuses, and a third retrieves the project list for reporting.

The key characteristic of UpStream API is that it inherits the logic of the WordPress REST API and WordPress user permissions. In other words, an external request should not be treated as a separate "magic" access point. It goes through WordPress authentication first, and then the add-on checks whether the user is allowed to manage UpStream objects.

In practice, the API add-on is useful in several situations:

• An agency wants to collect submissions from an external form and automatically create tasks inside a client's project.
• An internal dashboard needs to show project statuses without requiring managers to log into WordPress.
• A support site should turn reported issues into UpStream items so the team does not have to move data manually.
• A reporting system needs to regularly read task statuses, dates, and assignees.
• A developer wants to extend UpStream with local code without modifying the plugin core files.

That said, the API does not replace the entire UpStream interface. The documentation explicitly states that deleting objects through the API is not allowed, and private files are not supported in API file fields. So the right architecture usually looks like this: UpStream remains the main project management system, and the API handles automation, synchronization, and reporting.

Who This Workflow Is Right For, and When It Is Better Not to Overcomplicate the Site

The API add-on makes sense when the project has an external workflow that genuinely needs to read or update UpStream data. If the whole team works only inside the WordPress admin, clients use the standard project screen, and tasks are created manually, the API may just add another point of risk. Any external access requires authentication, logging, permission checks, backups, and a test environment.

When UpStream API Is a Good Fit

The add-on is a strong fit for developers and technical teams who understand REST requests, know how to keep secrets out of client-side JavaScript, and are prepared to validate server responses. It is especially useful for agencies where UpStream is used not as a personal task list, but as a real project database: clients, milestones, bugs, files, and assignees already live in WordPress, while a CRM, intake form, reporting dashboard, or separate support service sits alongside it.

The API is also justified when you want to reduce manual data transfer. For example, a manager creates a client in the CRM, and the integration creates a base project in UpStream. Or a tester files a bug in an external tracker, and a script adds a bug item to the WordPress project. In these scenarios, the purpose of the API is to reduce manual work, not to expose project data to everyone.

When You Should Stick with the UpStream Interface

If the site is maintained by one person without technical support, and the integration is only needed "just in case," do not start with the API. First set up the core UpStream workflow, user roles, clients, the frontend project view, notifications, and backups. Add the API only after it becomes clear which external system needs to exchange data and which fields it actually needs.

The add-on may also be a poor fit if you expect a full two-way interface with object deletion, private file operations, and complex business logic without any additional development. The UpStream API documentation covers GET, POST, and PUT for the main objects, but deletion remains an interface-level task. It is better to accept that limitation in the architecture than to work around it with unsafe custom edits.

Before enabling the API, ask one simple question: which external workflow will become faster or more reliable? If there is no clear answer, improve the standard UpStream workflow first.

What to Check Before Installing It on a Live Site

Preparation matters more than installation itself. The API works with project data, so a permissions mistake or a bad request can change statuses, create unwanted tasks, or expose more information than intended. A good starting point is a separate site copy, a test project, and a dedicated integration user.

Basic WordPress and UpStream Requirements

First, make sure the main UpStream plugin is installed, active, and running without critical errors. The WordPress.org page for UpStream lists the minimum requirements for the core plugin and includes a changelog, while the UpStream documentation reminds you to compare post-installation issues against the technical requirements. This is especially important for the API: if the project screen itself behaves inconsistently, an external request will only surface the same issue in a different form.

Check these three things:

• WordPress has a working core UpStream installation and at least one test project.
• The project includes a client, team members, milestones, and tasks, so API requests return a real structure rather than an empty system.
• The site runs over HTTPS if you plan to use authentication through the Authorization header.

Test Environment and Backup

Even if you are confident in the code, do not start with a production project. In a test environment, you can safely validate POST and PUT requests, make mistakes in field names, inspect the server response, and restore the original state. A minimal safe setup looks like this:

1. Create a backup of the WordPress database and files.
2. Deploy a copy of the site or prepare a separate test WordPress instance.
3. Create a dedicated UpStream test project with several tasks and bugs.
4. Create a separate WordPress user for the API. Do not use your personal administrator account for a permanent integration.
5. Validate all requests in a manual API client first, and only then move the logic into the external service.

You do not need real client data for the first run. It is better to use test names and artificial tasks so that any bad request does not affect actual client agreements.

User Permissions and the Risk of Overly Broad Access

The UpStream API documentation explicitly warns that access requires a WordPress REST API user with the manage_upstream capability, and a user with that level of access can manage UpStream objects regardless of the owner or client. This is a serious point. You should not grant API access to a standard client account just because that client needs to view one project.

Treat permissions as a separate setup stage. If the integration only needs to read statuses, do not give it unnecessary update operations. If the external service needs to create tasks, constrain the workflow in your own intermediary code: accept only the required fields, validate the project, filter status values, and log actions. The UpStream API layer gives you the capability, but the responsibility for a safe workflow still belongs to the integration owner.

Installing the Add-On and Running the Initial Validation

Installing UpStream API has two layers. First, the regular WordPress plugin or UpStream extension must be installed and activated. Second, the site must accept authenticated REST requests to UpStream routes. If you skip the second layer, the add-on may be active while the external client still receives 401, 403, 404, or empty responses.

An Installation Sequence with Minimal Risk

First install and activate the core UpStream plugin if it is not already enabled. The official installation guide for the core plugin walks through the Plugins and Add New screens, then searching for UpStream, installing it, and activating it. The UpStream documentation has separate materials for add-ons: they are installed as additional plugins, and add-on updates are checked either through the standard plugins screen or through the UpStream add-ons section.

For the API add-on, after activation, do not check for a separate pretty page. Check the route itself. Open the base WordPress REST API index in a browser or API client:

GET https://example.com/wp-json/

If the site returns the WordPress REST index, move on to the UpStream route. For testing, you can request a project by a known ID and explicitly specify the fields:

GET https://example.com/wp-json/upstream/v1/projects?id=PROJECT_ID&fields[]=title&fields[]=status

If the response only comes back after authentication, that is normal: the API works with project data. If you get a 404, check WordPress permalinks, confirm that the add-on is active, and verify the URL carefully. If you see 401 or 403, the issue is almost always user authentication or permissions.

How to Verify That the Request Actually Reached UpStream

Do not stop at "the page opened." Check three signals:

• The response includes the fields you requested through fields[], such as title and status.
• The values match the test project in the UpStream admin panel.
• After changing the test status through the interface, a repeated GET request returns the updated value.

This order saves time. If /wp-json/ itself is not working, there is no point debugging UpStream fields. If the REST index works but the UpStream route does not, look at the add-on, permalinks, or the endpoint name. If the route responds but blocks access, move on to authentication and permissions.

Authentication: How Not to Turn the API into a Weak Point on the Site

The official UpStream API document mentions JSON Basic Authentication for test scenarios and separately notes that it should not be used in a production environment. For modern sites, it is safer to consider WordPress Application Passwords, if they are available in your installation, or another proven server-side authentication method. The idea is simple: the external tool must authenticate the user, but it must not store the administrator's primary password.

Manual Testing with Application Passwords

Application Passwords in WordPress are created in the user profile and are specifically intended for programmatic access. The password is shown once, can be revoked independently of the user's normal password, and requests are sent through HTTP Basic Auth over HTTPS. For manual testing, it is convenient to use an API client or a command like this:

curl --user "api-user:APPLICATION_PASSWORD" \
  "https://example.com/wp-json/upstream/v1/projects?id=PROJECT_ID&fields[]=title&fields[]=status"

Do not put real usernames and passwords into public code, client-side JavaScript, a theme repository, or documentation for contractors. Store secrets in external service environment variables, in a secure vault, or in server-side application settings that are accessible only to an administrator.

Why You Should Not Grant Access from a Browser Script

It is sometimes tempting to call the UpStream API directly from JavaScript on a public page. That can be fine for reading public WordPress data, but it is usually a bad approach for UpStream projects. If the script contains credentials, the user can see them in the browser. If the script relies on the current session, you end up with a complicated permission model and risk exposing operations that should remain private.

A more reliable approach is to create an intermediary server-side layer. It accepts a safe request from the external system, validates the input, calls the UpStream API using a private secret, and returns only the required result. You can further restrict that layer by IP, integration key, request rate, and an allowlist of approved projects.

Checking the Authorization Header

If requests keep returning 401 even though the username and Application Password are correct, check whether the Authorization header is being stripped at the server, proxy, CDN, or security plugin level. This is a typical issue in WordPress REST integrations. The symptom is simple: the same request works locally or on another host, but fails on the production domain. If that happens, do not modify UpStream code. Check server configuration and security logs first.

Safe validation: create a separate API user, run one GET request against a test project, then revoke the password and confirm that the same request no longer works.

Object Map, Methods, and Required Parameters

Before writing the integration, create a data map. UpStream API does not work like a single "everything about everything" table. Each object has its own URL component, its own fields, and its own ID requirements. If you skip this mapping step, the errors will look mysterious: the project reads correctly, but the task does not; the status updates, but progress is rejected; the file is created, but the attachment never appears.

Main UpStream API Objects

The official documentation lists six object types. Each supports GET, POST, and PUT operations, and the URL component is used in the route after /wp-json/upstream/v1/.

This table is not just for the developer. It also helps the site administrator understand which data should be prepared before the integration: statuses, bug severities, categories, clients, users, and test projects.

GET: Read Only the Fields You Need

For GET requests, the documentation requires passing fields as a fields[] array. This is a good practice: the integration retrieves only what it needs instead of pulling the full object. Here is an example of reading the project title and status:

GET https://example.com/wp-json/upstream/v1/projects?id=PROJECT_ID&fields[]=title&fields[]=status

For tasks, files, and bugs, you need to pass not only the item ID itself, but also project_id. That is logical: these objects exist inside a project, and the API needs to understand the context.

GET https://example.com/wp-json/upstream/v1/tasks?id=TASK_ID&project_id=PROJECT_ID&fields[]=title

POST: Creating Objects

POST is used to create an object. The URL includes creator_id, and the data is sent in a JSON body. For a project, the minimum required field is title. For tasks, files, and bugs, you also need project_id because the item must be attached to a specific project.

POST https://example.com/wp-json/upstream/v1/tasks?project_id=PROJECT_ID&creator_id=USER_ID
Content-Type: application/json

{
  "title": "Check the contact form",
  "notes": "Task created by an external service after a client request."
}

After a POST request, do not assume the task exists until you validate the response. The documentation shows that when creating a task, the API returns the ID of the new object. You need to store that ID in the external system so later PUT requests update the same item instead of creating duplicates.

PUT: Updating Individual Fields

PUT updates an existing object. For a project, the URL is built with id; for tasks and bugs, project_id is added as well. The JSON body can contain one field or several. For example, an external service can update the task status and progress:

PUT https://example.com/wp-json/upstream/v1/tasks?id=TASK_ID&project_id=PROJECT_ID
Content-Type: application/json

{
  "status": "In Progress",
  "progress": 40
}

The important point here is not to invent values. Statuses must match the configured UpStream options, and task progress accepts integer values in the step format described in the documentation. If you send a status that does not exist in the settings, or an invalid progress value, the integration will either behave unpredictably or return an error.

DELETE: What the API Does Not Support

The documentation clearly states that deleting objects through the API is currently not allowed. That limitation can be turned into a safety rule: the external service can create and update, but cleanup and deletion remain inside the UpStream interface, where the administrator sees the context. If the integration needs to "cancel" a task, it is often safer to move it to a closed or canceled status, if such a status exists in your configuration, than to try deleting the record directly from the database.

Post-Installation Setup: From a Test Request to a Working Integration

After activating the add-on, do not connect a CRM or production service right away. First assemble the minimal set of settings that will repeat across any integration: the user, the authentication method, the allowlist of routes, the field map, request logging, and a rollback procedure. This turns the API from a "black box" into a manageable part of the site.

Integration User

Create a separate WordPress user for the external system. Do not use the site owner's account, the developer's personal account, or a shared admin login. The username and the Application Password description should clearly indicate the purpose, such as reporting dashboard integration or task import from a form. If you later need to disable the exchange, you can revoke one password or block one user without breaking access for the entire team.

When assigning the role, keep the UpStream API documentation warning about manage_upstream in mind. If your version of UpStream and add-on set does not provide a narrower option for the specific workflow, compensate for that with intermediary server-side code: do not give the external system arbitrary API access, allow only the pre-defined operations it actually needs.

Minimal Technical User Profile

For the first rollout, one technical user, one Application Password, and one test project are enough. Do not create multiple keys for different contractors until the logging model is clear. The fewer access points you have at the start, the easier it is to understand which request changed a specific task.

Field Map and Allowed Values

Before writing code, create a mapping table. For example, the external service field "Stage" may correspond to the project status, while the field "Owner" may correspond to assignedTo. But values should never be transferred blindly. If the external service sends "In Work" while UpStream stores the status as In Progress, you need an explicit translation dictionary.

A minimal mapping for a typical workflow includes:

• The external request ID - where the link to the UpStream object is stored.
• The UpStream project ID - which project is the parent of the task, bug, or file.
• The action author - which creator_id is used in POST requests.
• Statuses - which external system values are converted into UpStream statuses.
• Assignees - which WordPress user IDs can be assigned through assignedTo.
• Dates - where you normalize dates into the YYYY-MM-DD format.

Checking Permalinks and REST Routes

If the /wp-json/upstream/v1/... route cannot be found, check your WordPress permalinks. Sometimes it is enough to open Settings - Permalinks and save the settings without changing anything so WordPress rebuilds its routing rules. After that, repeat the request to the REST index, and only then try the UpStream route again.

Logging Without Storing Secrets

A production integration needs logs. The log should show the request time, operation type, route, project ID, external operation ID, HTTP status, and a short error message. But it should not store the Application Password, the Authorization header, real passwords, tokens, or unnecessary client personal data.

A good log helps you diagnose failures without becoming a new data leak. If the external service writes the full HTTP request together with secrets, disable that logging or mask the sensitive fields.

Rolling Back a Questionable Setting

Plan a rollback for every change. If the integration updates a project status, store the previous value. If it creates tasks, mark them with their source in the title or note so they can be found later. If it changes progress, keep an external log of "old value - new value." This is especially important because deletion through the API is not supported: cleaning up the results of a bad bulk POST will be harder than stopping the integration in advance.

Practical Scenario: A Client Request Turns into a Project Task

Let us look at a scenario that clearly shows the value of the UpStream API. An agency site has a contact form or an external support service. When a client reports a problem, a task needs to be created inside an existing UpStream project, assigned to the right person, and later updated after the work is done. This does not replace the entire support system, but it removes the need to manually copy text from the form into the project.

Goal

Automatically create a task in an UpStream project after an incoming request. The external system should store the ID of the created task so it can update the status later, while the manager should see the task in the normal project interface.

Preparation

Before testing, make sure you have:

• A test UpStream project with a known PROJECT_ID.
• A WordPress user with permission to manage UpStream and a separate Application Password.
• A clear creator_id for the user on whose behalf the task is created.
• A status dictionary so the external service does not send values that do not exist in UpStream.
• An API client for manual validation, such as Postman, Talend API Tester, or another tool.

Steps

Manual Validation Before Automation

Run the steps manually in an API client first. This separates field-mapping errors from bugs in the external service code. If a manual POST cannot create the task, the automation should not go live either.

1. Start with a GET request to the project and confirm that authentication works.
2. Create a task with a POST request to /tasks using project_id and creator_id.
3. Store the task ID from the API response in the external system.
4. Open the project in UpStream and verify that the task appeared in the correct project.
5. Send a PUT request to that task and update its status or progress.
6. Check the UpStream interface again to make sure the change is visible there, not just in the API response.

POST https://example.com/wp-json/upstream/v1/tasks?project_id=PROJECT_ID&creator_id=USER_ID
Content-Type: application/json

{
  "title": "Client request from the support form",
  "notes": "The client reported an issue on the contact page.",
  "status": "Open",
  "progress": 0
}

Validating the Result

After the request, do not check only the HTTP status. Open the project in UpStream, find the task, and review the title, note, status, and assignee if one was provided. Then send a GET request for the created task with project_id and request the same fields. If the interface and the API show the same data, the basic connection is working.

A Detail That Often Breaks the Workflow

The most common mistake is that the external service does not save the ID of the created task. Then the follow-up update no longer knows which object to modify, and the developer starts trying to find the task by title. That is unreliable: titles can repeat, the client may submit several similar requests, and the manager may rename the task. Save the ID immediately after a successful POST.

The second issue is progress and status. The documentation describes constraints for the progress field on tasks, and statuses must match the configured settings. So the external service should send only valid values. Do not trust freeform text from a form if it ends up in a structured UpStream field.

How to Work with Files, Clients, and Custom Fields

Integrations rarely stop at a task title. Sooner or later, the question comes up: can you send a file, link a task to a client, add custom fields, or sync client data? The important distinction here is between what UpStream supports in its interface and what is specifically documented for the API.

Files: Upload First, Then Link

For the files object, the API documentation describes fileId as the ID of a file in the WordPress Media Library. That means the file must be uploaded separately, and the API receives a reference to an existing media ID. It also states that private files are not supported through the API. If your workflow depends on protected attachments, do not treat the API as a full replacement for the UpStream file interface.

A safe approach looks like this: first decide which file types can be sent at all, where they are stored, who can access them, and how they are deleted. Then validate the API connection. If protected uploads are enabled in the project through UpStream, keep the official warning in mind: you should not switch the file manager mode after files have been added, because the WordPress media workflow and the protected manager workflow are incompatible.

Clients and Client Users

UpStream separates the client as an organization from client users as individual people with logins. The documentation emphasizes that a client is a company or organization, while client users are people who need their own logins, notifications, and tasks. This matters for the API: when you pass clientId or clientUserIds, you are linking the project to an existing structure, not just writing a client name as text.

If the external service creates projects from CRM data, do not mix up the contact person and the client organization. First determine whether that client already exists in UpStream, then map the users. If the CRM changes the client's team structure, remember the documented limitation: userIds for a client adds users, but does not remove users who were already added.

Custom Fields and Add-Ons

Custom Fields in UpStream let you add extra fields for projects, milestones, tasks, bugs, and files. The Custom Fields documentation lists field types and shows that fields can be used in the admin panel and, with Frontend Edit, on the public side of the site as well. But not every add-on automatically means convenient API support. If your integration needs custom fields, verify that on a test site and in the documentation for your version of the add-on.

A good practice is to sync the core fields that are explicitly documented in the API first: title, notes, status, dates, assignees, and client. Add custom fields as a second stage after manual validation. In the project notes or in the external log, record which fields are not yet synchronized so managers do not expect magic where the sources do not confirm support.

Checking the Result After Setup

Validating an API integration should look like a small acceptance test. One successful response is not enough. You need to make sure the data can be read, updated, displayed in the interface, kept within the intended permission model, and handled correctly when errors occur.

Minimum Test Set

For the first rollout, prepare a scenario with several requests:

1. GET the project by ID with the title and status fields.
2. GET a task with the required project_id.
3. POST a new test task into the test project.
4. PUT a status or progress change for that task.
5. GET the same task after the change.
6. Check the UpStream interface in the admin panel or on the frontend project screen.

If all steps pass, you can connect the external service in a limited test mode. If one step fails, do not move on. API integrations often break in a cascade: an incorrectly created task then fails to update, does not appear in a report, and creates duplicates.

What Counts as a Successful Result

Success is not just a 200 status code. A successful setup means:

• Requests succeed only with authentication and fail after the password is revoked.
• The external service operates through a test user, not through the administrator's personal account.
• The created objects are visible in UpStream and do not break the project structure.
• Statuses, dates, assignees, and progress match the allowed values.
• The integration log shows operations without exposing secrets.
• 401, 403, 404, and 5xx errors are handled with a clear message rather than endless retries.

Load Validation Without Extreme Testing

There is no need to start with hundreds of requests. Begin with a short series: create several tasks, update them, request their statuses. If the UpStream project is already large, keep user feedback about heavy projects and frontend load in mind: large projects with many tasks and attachments may require a more careful structure. Split the work across multiple projects if one project turns into a massive dumping ground for tasks.

For production mode, add rate limiting. If the external service retries POST every few seconds after a failure, it may create dozens of duplicates. It is safer to implement idempotency on your side: store the external request ID once, and have repeated requests update the existing task instead of creating a new one.

Common UpStream API Errors and How to Diagnose Them

API integration failures often look the same: "it does not work," "it does not create the task," "it returns forbidden," or "the status does not change." But the underlying causes differ. Below is a diagnostic map for common cases specifically related to REST access, UpStream permissions, and object structure.

The Request Returns 401 or 403

Symptom: the API client does not receive project data even though the URL looks correct. A 401 usually points to missing or invalid authentication, while a 403 usually means insufficient permissions. Possible causes include a wrong Application Password, a stripped Authorization header, a user without the required UpStream capability, or a security plugin blocking the REST request.

First, test a regular request to /wp-json/wp/v2/users/me using the same authentication method. If that fails, the issue is not UpStream. If it works but the UpStream route is forbidden, check the user's role and the manage_upstream capability. The rollback path is simple: revoke the Application Password, create a new one for the test user, and repeat the request without connecting the external service.

The Route Returns 404

Symptom: WordPress responds, but the UpStream endpoint cannot be found. Possible causes include the API add-on not being active, permalinks not being refreshed, a typo in the path, or a site running from a subdirectory with an incorrectly built base URL.

Check /wp-json/ first, then the exact /wp-json/upstream/v1/ prefix. Save the permalink settings in WordPress and repeat the request. If the route still does not appear, review the list of active plugins and confirm that the API add-on is installed.

GET for a Project Works, but a Task Cannot Be Found

Symptom: a request to projects returns data, but a request to tasks returns an error or an empty response. A common cause is a missing project_id. The documentation states that tasks, files, and bugs require the parent project ID.

Fix: store the pair of identifiers together - the item ID and the project ID. Do not try to retrieve a task by its own ID alone if the endpoint requires project context.

The Status or Bug Severity Does Not Save

Symptom: a PUT request succeeds only partially or returns an error, and the status or severity field does not change. The cause is that the value does not match the UpStream settings. The API should not have to guess that "ready," "Done," and "Closed" all mean the same thing.

Fix: create a dictionary of allowed values. Before sending the PUT request, convert the external value into the exact UpStream value. If a manager changes statuses in the UpStream settings, update the integration dictionary.

Task Progress Is Not Accepted

Symptom: the task is created, but the progress field does not update as expected. The documentation states that UpStream accepts task progress as integer values in a defined step range from 0 to 100. If the external service sends 37 or 62.5, those are invalid values.

Fix: round progress on the integration side to the allowed step and do not send fractional numbers. Immediately after the PUT request, run a GET request and compare the stored value.

The File Exists in the External System, but Does Not Attach in UpStream

Symptom: the file object is created, but the expected attachment does not appear. The API documentation requires a WordPress media fileId, and private files are not supported by the API. If you pass an external URL or a server path, that is not the same thing as a media ID.

Fix: first upload the file into WordPress using the correct workflow, get the media ID, and only then link it through the API. If the project uses the protected UpStream file manager, separately verify whether your workflow is compatible with the selected file mode.

Duplicates Appeared After a Bulk Import

Symptom: the same external ticket created the same UpStream task several times. The cause is that the external service retried the POST after a timeout or failed to store the ID of the created task. The API does not have to determine on its own that two requests are the same.

Fix: store the external ID and the UpStream task ID. Before sending a new POST request, check whether the object has already been created. If it has, send a PUT request instead of repeating the POST.

Safe Improvements for Developers

UpStream API is often used by developers, but that is not a reason to modify plugin files. The official documentation on changing frontend templates explicitly warns that the plugin core files must not be edited because updates will overwrite those changes. The same principle applies to API integrations: add your own layer separately instead of changing the internals of UpStream.

An Intermediary Route Instead of Direct External Access

For a serious integration, it is better to create a small server-side layer: your own plugin, a separate application, or a secure server function. It accepts the incoming request, verifies a signature or key, validates the fields, and only then calls the UpStream API. This reduces the risk that the external service ends up with overly broad permissions.

The principle can be described like this:

External service
  -> Your secure intermediary endpoint
  -> Validation and mapping
  -> UpStream API
  -> Log result without secrets

This kind of layer is especially useful when the external service should not know the WordPress Application Password. If the contractor changes, you update the key for your intermediary endpoint, while the WordPress password stays inside your infrastructure.

Field Allowlist

Do not forward the entire JSON payload you receive from outside to UpStream. Create an allowlist: title, notes, status, assignedTo, progress, and only the fields that are actually needed. Ignore everything else. This protects you from accidental fields, naming collisions, and attempts to alter the project structure through an unexpected parameter.

Dry Run During Rollout

Before enabling it in production, add a dry-run mode on your side. It should not replace real validation, but it helps show the manager exactly what will be created: the task title, project, assignee, status, and note. After approval, dry-run is turned off, and the same field map is used for the real POST request.

Rolling back this improvement is simple: disable the intermediary endpoint or return it to dry-run. The UpStream data remains untouched because all control lives outside the plugin core.

How UpStream API Relates to Other UpStream Add-Ons

UpStream consists of the core plugin and a set of add-ons. The API add-on does not exist in a vacuum: integration quality depends on which UpStream capabilities are already configured. If you use Custom Fields, Advanced Permissions, Frontend Edit, Calendar View, or Secure File Uploads, do not automatically assume the API will fully mirror every screen in those add-ons.

Advanced Permissions

Advanced Permissions lets you define flexible access to UpStream objects and fields through rules for roles and users. But the API documentation separately refers to a user with manage_upstream. So do not confuse the two levels: client-facing frontend permissions and technical API access. For an external integration, it is better to create a separate technical workflow where you explicitly control which operations are allowed.

Frontend Edit

Frontend Edit adds the ability to edit projects from the public side of the site. The API solves a different problem: it allows external code to create and update objects. If a client simply needs to edit tasks through the site, Frontend Edit may be enough. If an external system needs to create tasks automatically, you need the API or intermediary code.

Calendar View and Project Timeline

The calendar and timeline features rely on milestone, task, and bug dates. If the API integration updates startDate, endDate, or dueDate, the result may affect those visual add-ons. That is why dates must be valid, and the integration should validate the format before sending anything. One incorrect due date can visually disrupt the entire project calendar.

Custom Fields

Custom fields extend the data model, but they require separate validation. If your integration depends on those fields, first test reading and writing them on a staging copy. If you do not have confirmation, use the core API fields and store extra information in notes or in the external system until support for the required field is confirmed.

When UpStream API Is the Right Choice

UpStream API is worth using if you already have a working project base in UpStream and a clear external use case: create a task from a submission, update a status from a support service, display a report in a separate dashboard, or connect a CRM to WordPress projects. In that case, the add-on provides a useful bridge between UpStream and external systems instead of simply adding another technical layer.

Before moving to the live site, validate the test project, the separate API user, HTTPS, the Application Password or another safe authentication method, the field map, the allowed statuses, and the logging. After that, you can download the UpStream API package, install the add-on on a prepared copy of the site, and run through the validation scenario described above.

If the integration is only needed "someday," it is better to start with the basic UpStream setup, roles, clients, and frontend access. The API reveals the real strength of the product when there is a specific data-exchange workflow and a person responsible for security, logs, and ongoing maintenance.