Skip to main content

Project API Guide

This guide explains how to combine the project APIs and the library (Agents, playbooks, and skills) APIs to find executions that did not go well, investigate the cause, fix it, and check that it is fixed. For the fields and errors of each API, see the User API Reference (Projects) and the User API Reference (Conversations, Library, Organizations).

Before You Begin​

Token​

Use an application token (Authorization Code flow) for this flow. A system integration token can call only these project APIs: list projects, start, get, and cancel workflow runs, and fire triggers. It cannot read execution results or the library.

  • 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, rerun failed sweeps, resume closed runs (including reading the resume options), 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.
  • With a token of a user who does not sign in with SSO, many of the project APIs return 403 Forbidden (sso_required).
  • If the access token expires during long work, refresh it with the refresh token (Authentication Guide).

Scopes​

Choose the application's scopes in Console according to what you do (scopes in the Authentication Guide).

What you doScope
Read executions, records (audit trail), KPIs, project settings, review requests, connectors, queues, and the project libraryproject:read
Read Agents, playbooks, and skillsassets:read
Read execution conversations (the Agent's text along the way, command output, and so on)chat:history
Fix projects, steps, placements, sweeps, triggers, and webhooks, the deadline and reviewers of workflow runs, and the project libraryproject:write
Create, fix, and copy Agents, playbooks, and skillsassets:write
Delete Agents, playbooks, and skills you no longer needassets:delete
Start workflow runs, fire triggers, run failed sweeps again, resume closed workflow runs, and cancel workflow runsproject:run
Decide review requests and extend their due datesproject:decide

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 (for example, reason_code=guardrail_blocked; the value is case-sensitive).
  3. If needed, look at review decisions and changes to execution rules, members, and the definition in the records (audit trail) (GET /v1/projects/{projectId}/audit).
curl
curl "https://api.fd.agenticstar.tm.softbank.jp/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 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})
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 MCP servers it connected to, and the skill versions distributedusedSettings of the execution result
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 placements, and the goal and guardrail of the placed AgentsGet Project (GET /v1/projects/{projectId}). You can read them even for another user's non-public Agent if it is placed
The contents of Agents, playbooks, and skillsThe library get APIs. For skills, read the version list, the file list, a single file, or the download
Tool descriptions and agent cards of connectorsThe connector APIs (GET /v1/connectors/mcp/{connectionId} and GET /v1/connectors/a2a/{connectionId})
The result of the send of an external automation step (destination, HTTP status, time taken)automation in the execution result (automationHttpStatus in rows of the execution history)
The destination and body shape of an external automation stepautomationConfig of the step in Get Project, and the list of destinations (GET /v1/projects/automation-destinations)
The Agent's text along the way, commands and their output, and the full final responseThe execution conversation (GET /v1/conversations/{conversationId}/messages). Only the owner of the project at the time of the execution can read it (Execution Conversations)
  • The arguments passed to tools and what they returned are not recorded, so you cannot read them.
  • The final response of a workflow (summary) is up to 2000 characters. Read the full text in the execution conversation.
  • 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​

Choose How to Fix​

There are two ways to fix. They differ in where the fix applies and whether it is kept in the records (audit trail).

How to fixWhere it appliesWhat you can changeRecords (audit trail)
Fix the libraryEverywhere the Agent, playbook, or skill is used (including other projects). For a skill, only Agents and schedules that do not pin a version move to the new version (for a shared skill in a tenant where publishing approval is enabled, the previous version stays until approval)The fields of your own Agents, playbooks, and skillsNot kept
Fix the projectThis project onlyThe project, steps, placements (steps handled, memory, and sweeps), triggers (time and webhook starts), and project webhooks. You can also export the definition and import an exported definition (which creates a new project). Change connectors, members, notifications, execution rules, and "Start by email" on the screenChanges made this way to the definition of the project (name, description, tags, limits, lanes, report destinations and whether it is shared), steps, placements, triggers and project webhooks are kept (the recorder is the person who made the change; for a change that became pending approval, the request is kept under the requester and the change under the approver). Pausing and resuming, the organization, and the range of organizations it is shared with are not kept (changes to execution rules, members, and "Start by email" made on the screen are kept)

You can tell whether a placed Agent is also used in other projects from exclusiveToThisProject of the placement in Get Project. Fixing an Agent whose value is false in the library also affects the other projects. To fix it only in this project, follow Fix an Agent Only in This Project.

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, digest of the file list for skill files, and digest of Get Skill for skill settings).
  2. Send that value as baseDigest to the API that changes it. Only the fields you send change. However, arrays and orders (spec.skills and spec.inputFiles of an Agent, the order of steps, and the steps a placement handles), and the files sent to the API that replaces all skill files, 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. If the response does not have it (for example, after changing skill files), get it again.

Two edits that arrive at almost the same time can both go through (except editing skill documents). Avoid changing the same thing from several places.

curl
curl -X PATCH "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/$AGENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"baseDigest": "<digest from the get>", "spec": {"guardrail": "<fixed guardrail>"}}'

The APIs that create create another one when resent. If you did not receive a response, check in the list whether it was created, using the ID and createdAt, before resending, and delete any extra one that was created. With the APIs that copy, if you send an Idempotency-Key, resending with the same key returns the first copy and does not create another one (without the key, they behave like the APIs that create).

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, triggers and library bindings 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 status of definitionApproval in 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 with GET /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=pending and send that digest as baseDigest (sending the digest from the default read returns 409 Conflict (stale_base)).
  • If no response came back (a timeout or a cut connection), read with definition=pending and 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 the digest of the pending change as pendingDigest).
  • 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.

Fix Another User's Agent, Playbook, or Skill​

You cannot fix another user's items. Copy a public one and fix your copy. For a non-public one, ask the owner.

  • When you copy an Agent, the playbook and skills in it that are not your own are duplicated as your own, and input files that are not in your library are removed. In a tenant where publishing approval is enabled, a playbook that is not shared and a skill that is not shared or is inactive are removed instead of duplicated, and strippedResources in the response contains the name of the Agent (a public and active skill still points to the original skill; see Copy Agent). When you change spec of the copied Agent, 400 is returned unless the playbook is your own, a skill you newly point to is active and your own or public, and the input files are your own. When a skill the Agent already points to can no longer be used (for example, it is no longer public), 400 is not returned: the skill is removed and the Agent is saved, and the ID of the removed skill is returned in removedSkillIds in the response. If you keep using that skill, replace it with your own.
  • The input files attached to an Agent are passed as they are at execution time. They are not dropped even if they are not the project owner's files (after the ownership is transferred, the previous owner's files are still passed).

Fix an Agent Only in This Project​

To add to the instruction of an Agent that is also used in other projects, only in this project, use the placement's instruction (PATCH …/placements/{placementId}/instruction; it is passed after the Agent's goal, and the Agent itself is not changed). There is no dedicated API for fixing the Agent itself (its instruction, guardrail, skills, and so on) only in this project, rather than adding to it. Create a new Agent and replace it.

  1. Prepare a new Agent.
    • If the original is your own Agent, create one with the API that creates an Agent (POST /v1/agents) from name, description, and spec read with Get Agent. You cannot copy your own Agent (409 Conflict, already_owned).
    • If the original is another user's public Agent, copy it (POST /v1/agents/:agentId/copy).
  2. Fix the new Agent (PATCH /v1/agents/:agentId).
  3. 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"). For what pausing stops and does not stop, see the API that changes a project in Projects.
  4. Place the new Agent on the same steps as the original placement (POST /v1/projects/{projectId}/placements).
  5. Set the memory and the instruction of the original placement on the new placement (PATCH …/placements/{placementId}/memory and PATCH …/placements/{placementId}/instruction). For a cycle, also set the sweeps (PATCH …/placements/{placementId}/schedule).
  6. 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} with placementId and stepId). You can find what a Webhook trigger starts from triggers[].placementId in Get Project. Switch "Start by email" to the new placement on the screen (check what it starts on the screen too).
  7. Remove the original placement (DELETE /v1/projects/{projectId}/placements/{placementId}).
  8. If you paused the project, resume it (status set to "active").

This method has the following restrictions.

  • You must be able to read the original Agent (your own Agent or a public Agent). For another user's non-public Agent, ask the owner.
  • The new Agent can point only to your own playbooks, active skills that are your own or public, and your own input files. When you copy another user's Agent, the playbook and skills in it that are not your own are duplicated as your own, so you can fix it as is (in a tenant where publishing approval is enabled, a playbook that is not shared and a skill that is not shared or is inactive are removed, and strippedResources contains the name of the Agent; a public and active skill is not duplicated: it still points to the original skill, and uses the owner's current version unless a version is specified). If the original Agent is your own and the spec you read points to something that can no longer be used (such as a skill that is no longer public), replace it with your own before creating.
  • A new Agent can only have input files from your own library. If the original Agent's input files belong to someone else, prepare the same files in your own library before attaching them.
  • 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.
  • Fires and emails accepted before the pause may still run with the original Agent after the pause.
  • If other Agents are placed on the same step, the new placement runs last in a step whose placements run one at a time (in a step set to run at the same time, it runs together with the other placements). There is no API to reorder placements.
  • The placement ID changes. Past executions keep the original placement ID.
  • Placing and removing placements are also kept in the records (audit trail) as changes to the definition.

Fix a Skill​

  • Documents (.md, .json, .yaml, and .yml) can be fixed with the API that edits skill documents (PATCH /v1/skills/:skillId/files). Send the digest you received from getting the file list (GET /v1/skills/:skillId/files, read without version_id) as baseDigest. Without it, 400 is returned; if the skill has changed since you read it, 409 Conflict (stale_base) is returned.
  • A skill that contains scripts or executables is fixed, including its documents, with the API that replaces all skill files (PUT /v1/skills/:skillId/files). Download the current version (GET /v1/skills/:skillId/download), fix it on your side, and send all the files. Files that are not documents, such as configuration files, are also fixed by replacing all files. When you replace all files, also send the digest you received from getting the file list as baseDigest (if the skill has changed since you read it, 409 Conflict (stale_base) is returned).
  • To get all the files of an earlier version, copy the skill with that version specified (POST /v1/skills/:skillId/copy), and download the copied skill.
  • Do not publish a skill that contains secrets (configuration files and the like). Once it is public, other users can read all its files. Even if you remove the secrets in a new version, they can be taken out by copying with the earlier version specified.

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". Resuming a closed run happens only when an owner or operator (including people with the organization operations role) does it, never automatically, so if you follow a "closed_rejected" or "closed_failed" run until it is resumed, get it again within a time limit you decide, or look for run.resumed in the audit log.
    • 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. If you fixed a skill, check in usedSettings of the execution result that the new version was distributed (for a shared skill in a tenant where publishing approval is enabled, the new version is not distributed until it is approved). An Agent that pins a version does not move to the new version, so change versionId in spec.skills of the Agent to the new version.
  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.

Changes to the library (agents, playbooks and skills), and pausing and resuming, the organization, and the range of organizations a project is shared with changed with these APIs, are not kept in the records (audit trail). Keep track of what you changed and when on your side. Other project changes made with these APIs (including library bindings of placements) are kept in the records (audit trail) (the recorder is as in the table in Choose How to Fix).