Project API Guide
This guide explains how to combine the project APIs to find executions that did not go well, investigate the cause, fix the steps and placements, and check that it is fixed. For the fields and errors of each API, see the User API Reference (Projects).
Before You Begin
Token
Use an application token (sign-in from an external tool) for this flow. A system integration token can call only these project APIs: list projects, start and get workflow runs, fire triggers, list and get the artifacts of workflow runs, cancel workflow runs, stop sweep executions of cycle projects, and get the results of executions (status fields only).
- Whether you can call an API depends on the token user's role in the project. Members can read; members and people with the organization operations role can start runs and fire triggers; owners and operators (including people with the organization operations role) can set run deadlines, reassign reviewers, cancel runs others started, and pause or resume the project (the person who started a run can also cancel it); owners can make other changes to the project; and reviewers and their delegates during the delegation period can decide review requests (Who Can Call and 404 / 403). People with the organization operations role can call some of the read APIs and the operations that run the project, even without taking part in the project.
- If the access token expires during long work, refresh it with the refresh token (Authentication Guide — Authorization Code Flow).
- The Marketplace edition applies no scope restrictions.
1. Find Executions That Did Not Go Well
- Look at the Agent completion rate and the number per outcome in the KPIs (
GET /v1/projects/{projectId}/kpi) to get an idea of which failures increased. Choose the period from the latest 7, 30, or 90 days. - List the executions that did not go well by filtering the execution history (
GET /v1/projects/{projectId}/executions) withoutcome=problemsand a period (fromandto). List executions without a recorded result withoutcome=missing. To filter by the reason for the outcome (reasonCode), addreason_code(the value is case-sensitive). - If needed, look at review decisions and changes to members and the definition in the records (audit trail) (
GET /v1/projects/{projectId}/audit).
curl "https://<your-domain>/api/v1/projects/$PROJECT_ID/executions?outcome=problems&from=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer $ACCESS_TOKEN"
For the outcome values and what the screen shows, see Outcome Values.
2. Investigate the Cause
For the execution you found (executionId), read what you need to know.
| What you want to know | API to read |
|---|---|
| Whether the registered Agent reported that it finished, its reason and comment, and the final response | envelope.completionReport and summary of the execution result (GET /v1/projects/{projectId}/executions/{executionId}). The contents are what the registered Agent reported |
| Which tools it called, whether they succeeded or were stopped, and how long they took | The list of tool calls (…/executions/{executionId}/operations). Read to the end with cursor |
| The request, whether the input guardrail stopped it, and questions from the Agent | The execution timeline (…/executions/{executionId}/timeline) |
| The steps, placements, and connectors when the workflow run started | The settings of the workflow run (GET /v1/projects/{projectId}/runs/{runId}/config). A cycle has none, so read the current values with Get Project |
| The current case config of the workflow run (the input files, parameters, and connectors for each placement and step) | Get Run Case Config (GET /v1/projects/{projectId}/runs/{runId}/case-config; see Get Run Case Config) |
| The current steps and placements | Get Project (GET /v1/projects/{projectId}) |
| Artifacts of a workflow run (the input files bound at the start and the outputs made by the steps) | The artifact list (GET /v1/projects/{projectId}/artifacts?run_id=…) and the contents (…/artifacts/{artifactId}/content) |
| Tool descriptions and agent cards of connectors | The connector APIs (GET /v1/connectors/mcp/{connectionId} and GET /v1/connectors/a2a/{connectionId}) |
| The text along the way and the full final response of a cycle sweep | The execution conversation (GET /v1/conversations/{conversationId}/messages; Execution Conversations) |
- The arguments passed to tools and what they returned are not recorded, so you cannot read them.
- For a cycle, the steps, placements, and connectors used at the time of an execution are not kept. You can only compare with the current values.
3. Fix the Steps and Placements
What You Can Fix
| What to fix | How to fix |
|---|---|
| How the registered Agent works inside (what it does and how it answers) | It cannot be fixed with the project APIs. The developer who made the registered Agent fixes it, and the administrator registers it again (Develop) |
| Steps (name, description, review step settings, where to send back, and step times) | The API that changes a step (PATCH /v1/projects/{projectId}/steps/{stepId}) |
| The order and number of steps | The APIs that add, reorder, and delete steps |
| The registered Agent placed on a step | Replace a Registered Agent below |
| The steps a placement handles | The API that changes the steps a placement handles (PUT …/placements/{placementId}/steps) |
| Cycle sweeps | The API that changes sweeps (PATCH …/placements/{placementId}/schedule) |
| Triggers (time and webhook starts) | The APIs that create, change, and delete a trigger (POST …/triggers, PATCH and DELETE …/triggers/{triggerId}; Triggers) |
| Project webhooks (telling another service about events) | The webhook APIs (POST …/webhooks, PATCH and DELETE …/webhooks/{webhookId}; Webhooks) |
| A placement's step settings (workflow: the registered Agent's parameters, the connectors for connection slots, passing a previous step's output; cycle: environment variables) | The API that writes step settings (PUT …/placements/{placementId}/steps/{stepId}/runtime-config) |
| The case config of a workflow run waiting for review (input files, parameters, and connectors) | The API that replaces the case config (PUT …/runs/{runId}/case-config; only while the run waits for review, and only by an owner; see Update Run Case Config) |
| Take the definition of a project to another environment | The API that exports the definition (GET …/definition) and the API that creates a project from an exported definition (POST /v1/projects/import; see Import) |
The Editing Flow
Call the APIs that change something that already exists in the following flow (Editing and Resending).
- Get it, and note
digestin the response. Which get'sdigestto use is described in the API that changes it (for example, for a step,digestof the step in Get Project). - Send that value as
baseDigestto the API that changes it. Only the fields you send change. However, the order of steps, the steps a placement handles, and the step settings of a placement (runtime-config) are replaced entirely with what you send. - If
409 Conflict(stale_base) is returned, another change was made after you got it. Get it again, review what you change, and send again. - To keep changing the same thing, you can use
digestin the response.
Only the API that replaces the case config checks a version number instead of digest. Send the revision you read with Get Run Case Config as expectedRevision; if it differs, 409 Conflict (revision_conflict) is returned. Get it again, review what you change, and send again.
Two edits that arrive at almost the same time can both go through. Avoid changing the same thing from several places.
curl -X PATCH "https://<your-domain>/api/v1/projects/$PROJECT_ID/steps/$STEP_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"baseDigest": "<digest of the step>", "description": "<fixed description>"}'
The APIs that create create another one when resent. If you did not receive a response, check with a get whether it was created before resending, and delete any extra one that was created.
Tenants That Require Approval for Definition Changes
When the tenant requires approval for definition changes (an administrator setting), changes made by the APIs that change a project, steps, placements and triggers do not take effect at once and become pending approval (changes to the name, description, tags and whether the project is shared do not become pending and take effect at once).
- If
statusofdefinitionApprovalin the response of a write API is"pending", the change is pending approval. Until it is approved, runs use the previous (approved) definition. Read a summary of the pending change withGET /v1/projects/{projectId}/definition-approval. - Approving or sending back is done by an approver (another owner or an administrator of the organization, other than the requester) on the product screen. It cannot be decided with the API.
- A pending change does not appear in the default read. To make further changes, read with
definition=pendingand send thatdigestasbaseDigest(sending thedigestfrom the default read returns409 Conflict(stale_base)). - If no response came back (a timeout or a cut connection), read with
definition=pendingand check whether the change went in before retrying. If you retry an API that creates something (steps, placements, triggers) without checking, the pending change can end up with two of the same thing. For the API that creates a project, the project may have been created, so check the list of projects (GET /v1/projects) before retrying. - An owner can withdraw the pending change (
DELETE /v1/projects/{projectId}/definition-approval, with thedigestof the pending change aspendingDigest). - When you create a project, its first definition also becomes pending. Until it is approved, workflow runs cannot start (
409 Conflict,definition_pending).
Even in a tenant that does not require approval, each write that changes the definition is kept as a version of the definition and in the records (audit trail). When a project is created, only the first version is kept, with no rows in the records (audit trail). A write that leaves the content the same as the previous version adds neither a version nor records. When writes to the same project overlap, they may be combined into one version depending on timing; in that case the caller who recorded the version first is the recorder. If a record comes in between, there are two versions.
Replace a Registered Agent
There is no dedicated API for replacing the registered Agent placed on a step with another registered Agent. Place a new placement, and then remove the original placement.
- Find registered Agents you can place with Get Agent Candidates (
GET /v1/projects/agent-candidates?project_type=workflow; for a cycle,project_type=cycle). Only registered Agents whosecertifiedis true can be placed in a workflow project. - Do this when no workflow run is in progress (get the list of workflow runs with
limit=100, and check that none hasstatus"running"or"waiting_gate"). To keep the original and new Agents from both running, pause the project (PATCH /v1/projects/{projectId}withstatusset to"paused"). - Place the new registered Agent on the same steps as the original placement (
POST /v1/projects/{projectId}/placementswithmarketplaceAgentIdandstepIds). For a cycle, also set the sweeps (PATCH …/placements/{placementId}/schedule). - Switch Webhook triggers that start the original placement to the new placement with the API that changes a trigger (
PATCH /v1/projects/{projectId}/triggers/{triggerId}withplacementIdandstepId). You can find what a Webhook trigger starts fromtriggers[].placementIdin Get Project. - Remove the original placement (
DELETE /v1/projects/{projectId}/placements/{placementId}). - If you paused the project, resume it (
statusset to"active").
- The placement ID changes. Past executions keep the original placement ID.
- Pausing does not stop running executions. Filter the execution history with
outcome=running, and replace the Agent after they finish. - In a paused project, a workflow run in progress does not move to its next step and does not finish until the project is resumed. Finish running workflow runs before pausing.
- The list of workflow runs shows only the latest 100. An older workflow run still waiting for a review cannot be found in the list.
- If other registered Agents are placed on the same step, the new placement runs last. There is no API to reorder placements.
4. Check That It Is Fixed
- After fixing, cause an execution.
- For a workflow, start a workflow run (
POST /v1/projects/{projectId}/runs; theIdempotency-Keyheader is required), and check its progress with Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}). When you wait for it to end, stop whenstatusbecomes"closed_done","closed_rejected","closed_failed", or"cancelled". Check the input files bound at the start and the artifacts made by the steps with the artifact list and contents. To stop it, cancel the workflow run (POST /v1/projects/{projectId}/runs/{runId}/cancel; the body needscommandId). - For a cycle, fire a Webhook trigger (
POST /v1/projects/{projectId}/triggers/{triggerId}/fire; the body needs aneventIdthat is unique to each fire, and a resend of the same fire uses the same value), and find the execution as described in Finding the Execution Started by a Fire. To stop a running sweep execution, usePOST /v1/projects/{projectId}/executions/{executionId}/cancel(it can take about a minute to stop).
- For a workflow, start a workflow run (
- Compare the result of the new execution with the executions before the fix.
- After it has run for a while, compare by filtering the execution history to periods before and after the day of the fix. The KPI period is only the latest 7, 30, or 90 days and cannot be split at the day of the fix.
Keep track of what you changed and when on your side.