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 and get 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, owners can change the project, start runs, and fire triggers, and reviewers can decide review requests (Who Can Call and 404 / 403).
• 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 do	Scope
Read executions, records (audit trail), KPIs, project settings, review requests, and connectors	project:read
Read Agents, playbooks, and skills	assets:read
Read execution conversations (the Agent's text along the way, command output, and so on)	chat:history
Fix projects, steps, placements, and sweeps	project:write
Create, fix, and copy Agents, playbooks, and skills	assets:write
Delete Agents, playbooks, and skills you no longer need	assets:delete
Start workflow runs and fire triggers	project:run
Decide review requests	project: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. You cannot filter by the reason for the outcome (reasonCode), so filter the list you got on your side.
3. If needed, look at review decisions and changes to execution rules and members 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 know	API to read
Whether the 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})
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 MCP servers it connected to, and the skill versions distributed	usedSettings of the execution result
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 steps and placements, and the goal and guardrail of the placed Agents	Get 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 skills	The library get APIs. For skills, read the version list, the file list, a single file, or the download
Tool descriptions and agent cards of connectors	The connector APIs (GET /v1/connectors/mcp/{connectionId} and GET /v1/connectors/a2a/{connectionId})
The Agent's text along the way, commands and their output, and the full final response	The execution conversation (GET /v1/conversations/{conversationId}/messages). Only the person who created the project 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 fix	Where it applies	What you can change	Records (audit trail)
Fix the library	Everywhere 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	The fields of your own Agents, playbooks, and skills	Not kept
Fix the project	This project only	The project, steps, and placements (steps handled, memory, and sweeps). Change triggers, connectors, members, notifications, and execution rules on the screen	Of what you can change this way, only changes to reviewers and the review method are kept (changes to execution rules, members, and "Start by email" made on the screen are also 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 and copy 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.

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.

• Even after you copy an Agent, its playbook, skills, and input files still point to the original user's items. When you change spec of the copied Agent, replace the playbook with your own, the skills with your own or public ones, and the input files with your own. Otherwise, 400 is returned.
• Of an Agent's input files, only those of the person who created the project are passed at execution time. Other people's files are dropped without an error.

Fix an Agent Only in This Project

There is no dedicated API for fixing an Agent that is also used in other projects only in this project. 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 of the original placement on the new placement (PATCH …/placements/{placementId}/memory). For a cycle, also set the sweeps (PATCH …/placements/{placementId}/schedule).
6. On the screen, switch Webhook triggers and "Start by email" 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. Check what "Start by email" starts on the screen.
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, your own or public skills, and your own input files. If the original Agent points to another user's playbook or skills, copy the public ones to make them your own (you can point to a public skill as is). For non-public ones, ask the owner.
• Only the input files of the person who created the project are passed at execution time. So only the person who created the project can fix an Agent that uses input files with this method.
• 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 not kept in the records (audit trail) (switching "Start by email" is kept).

Fix a Skill

• Documents (.md, .json, .yaml, and .yml) can be fixed with the API that edits skill documents (PATCH /v1/skills/:skillId/files).
• 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.
• 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}).
   • 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. 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.

Library changes, and project changes made with these APIs (except reviewers and the review method), are not kept in the records (audit trail). Keep track of what you changed and when on your side.