# 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md) and the [User API Reference (Conversations, Library, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md).

## 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#common-access)). 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md)).

### Scopes

Choose the application's scopes in Console according to what you do ([scopes in the Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md)).

| What you do                                                                                                                           | Scope            |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| Read executions, records (audit trail), KPIs, project settings, review requests, connectors, queues, and the project library          | `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, sweeps, triggers, and webhooks, the deadline and reviewers of workflow runs, and the project library | `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, fire triggers, run failed sweeps again, resume closed workflow runs, and cancel workflow runs                    | `project:run`    |
| Decide review requests and extend their due dates                                                                                     | `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`. 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`).

```bash
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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#execution-outcomes).

## 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 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 step                                | `automationConfig` 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 response       | The execution conversation (`GET /v1/conversations/{conversationId}/messages`). Only the owner of the project at the time of the execution can read it ([Execution Conversations](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#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 (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 skills                                                                                                                                                                                                                                                                             | Not kept                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Fix the project | This project only                                                                                                                                                                                                                                                                      | The 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 screen | Changes 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](#fix-this-project-only).

### The Editing Flow

Call the APIs that change something that already exists in the following flow ([Editing and Resending](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#common-update)).

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.

```bash
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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#triggers-find-execution).

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](#choose)).
