Skip to main content

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, and fire triggers. It cannot read execution results or artifacts.

  • Whether you can call an API depends on the token user's role in the project. Members can read, owners can change the project, start runs, and fire triggers, and reviewers can decide review requests (Who Can Call and 404 / 403).
  • 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​

  1. 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.
  2. List the executions that did not go well by filtering the execution history (GET /v1/projects/{projectId}/executions) with outcome=problems and a period (from and to). List executions without a recorded result with outcome=missing. To filter by the reason for the outcome (reasonCode), add reason_code (the value is case-sensitive).
  3. If needed, look at review decisions and changes to members in the records (audit trail) (GET /v1/projects/{projectId}/audit).
curl
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 knowAPI to read
Whether the registered Agent reported that it finished, its reason and comment, and the final responseenvelope.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 tookThe 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 AgentThe execution timeline (…/executions/{executionId}/timeline)
The steps, placements, and connectors when the workflow run startedThe 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 steps and placementsGet Project (GET /v1/projects/{projectId})
The artifacts made by the steps of a workflowThe artifact list (GET /v1/projects/{projectId}/artifacts?run_id=…) and the contents (…/artifacts/{artifactId}/content)
Tool descriptions and agent cards of connectorsThe 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 sweepThe 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 fixHow 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 stepsThe APIs that add, reorder, and delete steps
The registered Agent placed on a stepReplace a Registered Agent below
The steps a placement handlesThe API that changes the steps a placement handles (PUT …/placements/{placementId}/steps)
Cycle sweepsThe API that changes sweeps (PATCH …/placements/{placementId}/schedule)

The Editing Flow​

Call the APIs that change something that already exists in the following flow (Editing and Resending).

  1. Get it, and note digest in the response. Which get's digest to use is described in the API that changes it (for example, for a step, digest of the step in Get Project).
  2. Send that value as baseDigest to the API that changes it. Only the fields you send change. However, the order of steps and the steps a placement handles are replaced with what you send.
  3. 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.
  4. To keep changing the same thing, you can use digest in the response.

Two edits that arrive at almost the same time can both go through. Avoid changing the same thing from several places.

curl
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.

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.

  1. 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 whose certified is true can be placed in a workflow project.
  2. Do this when no workflow run is in progress (get the list of workflow runs with limit=100, and check that none has status "running" or "waiting_gate"). To keep the original and new Agents from both running, pause the project (PATCH /v1/projects/{projectId} with status set to "paused").
  3. Place the new registered Agent on the same steps as the original placement (POST /v1/projects/{projectId}/placements with marketplaceAgentId and stepIds). For a cycle, also set the sweeps (PATCH …/placements/{placementId}/schedule).
  4. On the screen, switch Webhook triggers that start the original placement to the new placement. Triggers cannot be changed with the external API. You can find what a Webhook trigger starts from triggers[].placementId in Get Project.
  5. Remove the original placement (DELETE /v1/projects/{projectId}/placements/{placementId}).
  6. If you paused the project, resume it (status set 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​

  1. After fixing, cause an execution.
    • For a workflow, start a workflow run (POST /v1/projects/{projectId}/runs; the Idempotency-Key header 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 when status becomes "closed_done", "closed_rejected", "closed_failed", or "cancelled". Check the artifacts made by the steps with the artifact list and contents.
    • For a cycle, fire a Webhook trigger (POST /v1/projects/{projectId}/triggers/{triggerId}/fire; the body needs an eventId that 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.
  2. Compare the result of the new execution with the executions before the fix.
  3. 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.