# User API Reference (Projects)

This is the reference for the SaaS user-facing APIs that handle projects. With an application token, you can create and configure projects, place Agents, start workflow runs, check the results of executions, and decide review requests. For the conversation, library (Agents, playbooks, and skills), and organization APIs, see [User API Reference (Conversations, Library, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md). For how to combine the APIs to investigate and fix executions that did not go well, see the [Project API Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/project-api-guide.md).

A system integration token can call only five project APIs: list projects, start a workflow run, fire a trigger, get a workflow run, and cancel a workflow run ([System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md)). Calling any other API on this page with a system integration token returns `403 Forbidden` (`forbidden`).

## Base URL

All API requests are sent to the following base URL.

SaaS

`https://api.fd.agenticstar.tm.softbank.jp/api`

Endpoint paths in this document are relative to the base URL.

## Authentication

Every API request must include a Bearer token in the `Authorization` header.

```text
Authorization: Bearer <access_token>
```

If the token is invalid or missing, `401 Unauthorized` is returned. The APIs on this page use the following scopes. If a required scope is missing, `403 Forbidden` (`insufficient_scope`) is returned.

| Scope            | What it allows                                                                                                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project:read`   | Read projects and what they contain (steps, placements, executions, records (audit trail), KPIs, the library, and so on), review requests, connectors, and queues                                                     |
| `project:write`  | Create and edit projects, change steps and placements, create, change, and delete triggers and webhooks, change the deadline and reviewers of workflow runs, and add, change, and delete files in the project library |
| `project:delete` | Delete projects                                                                                                                                                                                                       |
| `project:run`    | Start workflow runs, fire triggers, run failed sweeps again, resume closed workflow runs, and cancel workflow runs                                                                                                    |
| `project:decide` | Decide review requests and extend their due dates                                                                                                                                                                     |

The `project:*` scopes work only when the name matches exactly. For how to obtain tokens and details on scopes, see the [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md) and the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/auth-saas-ref.md).

## Common Rules

These rules apply to the APIs on this page.

### Who Can Call and 404 / 403

Whether you can call an operation depends on your role in the project (○ = can call, × = cannot call).

| Operation                                                                                                                                              | Owner | Operator | Member                                                                 | Organization operations role \*1 | Refusal for those who cannot call                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | -------- | ---------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Read the project and what is in it (steps, placements, runs, and so on)                                                                                | ○     | ○        | ○                                                                      | Partly \*2                       | —                                                                                                                                            |
| Start a workflow run and fire a trigger                                                                                                                | ○     | ○        | ○                                                                      | ○                                | —                                                                                                                                            |
| Other operating operations \*3                                                                                                                         | ○     | ○        | × (cancelling a workflow run is ○ for the person who started that run) | ○                                | `403 Forbidden` (`operator_only`)                                                                                                            |
| Register, import, add a new version of, restore a previous version of, and import the new version of the source deliverable for a project library file | ○     | ○        | ○                                                                      | ×                                | A person with the organization operations role who does not take part gets `409 Conflict` (`forbidden_role`)                                 |
| Webhook APIs (including the list and delivery results)                                                                                                 | ○     | ×        | ×                                                                      | ×                                | `403 Forbidden` (`owner_only`). A person with the organization operations role who does not take part gets `409 Conflict` (`forbidden_role`) |
| Other write APIs (except the API that creates a project)                                                                                               | ○     | ×        | ×                                                                      | ×                                | `403 Forbidden` (`owner_only`). A person with the organization operations role who does not take part gets `409 Conflict` (`forbidden_role`) |

- \*1 A person who has the organization operations role (the "Operations" role assigned under "Admin Roles" in the admin console) in the organization the project belongs to. Even if they do not take part in the project, they can call the operations marked ○ in the table. If a participant also has this role, they can call operating operations in addition to their participation role.
- \*2 For a person with the organization operations role who does not take part, getting
  <!-- -->
  the project library
  <!-- -->
  and getting the pending definition approval returns `409 Conflict` (`forbidden_role`), and the contents of a project file returns `400 Bad Request` (`file_not_found`). The agent text and file fields of workflow runs and executions are returned as null or empty.
- \*3
  <!-- -->
  Setting the deadline of a workflow run, reassigning approvers, rerunning a failed sweep, resuming a closed workflow run and getting its resume options, cancelling a workflow run, and pausing and resuming a project
  <!-- -->
  .
- Who can call the work item, queue, and connector APIs is described in each section.

| Situation                                                                                                                                             | What is returned                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A project of which you are neither a member nor a person with the organization operations role in its organization, and a project that does not exist | Both return `404 Not Found`, and they cannot be told apart from the response. However, for a published project, even a non-member can read only the structure with Get project (`GET /v1/projects/{projectId}`)                                                                                                                                 |
| `404 Not Found` code                                                                                                                                  | One per endpoint, and it is the name of the last resource in the path (for example, the placement API returns `placement_not_found` and the execution API returns `execution_not_found`). An endpoint whose path has no resource ID returns `project_not_found`. When the project is not visible, the code of that endpoint is returned as well |
| An ID specified in the body (agent, step, user, and so on) does not exist or is not visible                                                           | It differs by endpoint (for example, for a placement, `agentId` returns `400 Bad Request` (`agent_not_found`) and `stepIds` returns `400 Bad Request` (`invalid_parameter`)). See the description and error responses of each endpoint                                                                                                          |
| A nonexistent ID specified in a list filter query (`placement_id`, `step_id`, `run_id`)                                                               | An empty list is returned                                                                                                                                                                                                                                                                                                                       |
| The token of a user who is not logged in by SSO                                                                                                       | `403 Forbidden` (`sso_required`) is returned by the project, work item, and queue APIs (except getting the project list, starting a workflow run, firing a trigger, and getting a workflow run).                                                                                                                                                |

"Not a member" in the 404 rows of the error tables on this page means that the person is neither a member nor a person with the organization operations role in the organization the project belongs to.

### Request Handling

Send the body as a JSON object (<!-- -->the API that sends a file to the project library<!-- --> uses `multipart/form-data`).

| What you sent                                                                                               | How it is handled                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Query parameters and body fields not in the specification                                                   | Ignored                                                                                                                                                                                                                                                                |
| An invalid value for a query parameter in the specification, or a `cursor` that cannot be read              | `400 Bad Request`                                                                                                                                                                                                                                                      |
| An invalid URL encoding in a path parameter value (a `%` sequence)                                          | `400 Bad Request` (`invalid_parameter`)                                                                                                                                                                                                                                |
| A body other than `Content-Type: application/json`, or a body with an unsupported character set (`charset`) | `415 Unsupported Media Type` (`unsupported_media_type`)                                                                                                                                                                                                                |
| Malformed JSON, or a body that is not a JSON object                                                         | `400 Bad Request` (`invalid_body`)                                                                                                                                                                                                                                     |
| A field that this API has decided not to accept                                                             | `400 Bad Request` (`invalid_parameter`). It is not silently ignored because you would believe it was changed when it was not. The fields concerned are described in each endpoint                                                                                      |
| Query names                                                                                                 | snake\_case (`my_role`, `placement_id`, `step_id`, `run_id`, `project_id`). The previous names (`myRole`, `placementId`, `stepId`, `runId`, `projectId`) are also accepted. Specifying different values for both names returns `400 Bad Request` (`invalid_parameter`) |

The body limits are as follows. A larger body returns `413 Payload Too Large` (`body_too_large`).

| API                                                                          | Body limit            |
| ---------------------------------------------------------------------------- | --------------------- |
| Create a project, import a definition, decide a work item, extend a deadline | 3 MiB                 |
| Add or change a step                                                         | 32 KiB                |
| Send a file to the project library                                           | Up to 512 MB per file |
| Other APIs                                                                   | 16 KiB                |

Responses carry an `x-request-id` header. The service assigns this value; a value you send in the request is not used. Please tell us this value when you contact us.

### Editing and Resending

For the APIs that change something, put the `digest` returned by the get API into `baseDigest` and send it. If another change was made after you got it, `409 Conflict` (`stale_base`) is returned. Get it again and resend.

- The `digest` in the response is the value after the edit. You can use it for the next edit.
- Two changes that arrive at almost the same time may both succeed.
- Extending a work item deadline and setting a workflow run deadline or reassigning approvers do not use `baseDigest` (they are not compared with changes made after you got it).
- In a tenant where changes to the definition require approval, check that a change arrived by getting with `definition=pending` (a change waiting for approval does not appear in the default get).

Resends are handled as follows.

| API                                                                                         | What identifies a resend                  | Resending with the same value                                                                             |
| ------------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Start a workflow run                                                                        | The `Idempotency-Key` header (required)   | The result of the first request is returned                                                               |
| Fire a trigger                                                                              | `eventId` in the body                     | The result of the first request is returned                                                               |
| Decide a work item, reassign approvers, resume a closed workflow run, cancel a workflow run | `commandId` in the body                   | The result of the first request is returned (see the description of each endpoint for how it is returned) |
| Place an agent                                                                              | The same agent and the same assigned step | The existing placement is returned                                                                        |
| Create a project, create a step                                                             | —                                         | Another one is created. Before resending, check whether it was created by listing or getting the projects |

### Fields About People

- User names and email addresses are returned only in the member list (`members`) of Get Project (`GET /v1/projects/{projectId}`). Other fields return only user IDs.
- The owner of a resource is `ownerUserId` (the owner of a placed Agent is `agentOwnerUserId`), people in settings are `approverUserIds` and `escalateToUserId`, and the requester of a review request is `requesterUserId`.
- Who did something is returned as a pair of `…Kind` (kind) and `…Ref` (reference). When `…Kind` is `"human"`, `…Ref` is a user ID. Otherwise, `…Ref` is `client:<integration ID>` for a system integration, or another reference such as `system:…`. Even when there is no value, the field is not omitted and is returned as null. As an exception, what started a workflow run is returned only as `startedByRef` (there is no kind field; see Get a Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}`) for the values).

### Pagination

| Parameter | Type      | Description                                                                       |
| --------- | --------- | --------------------------------------------------------------------------------- |
| `limit`   | `integer` | Number of items per page (1-100). Defaults to 50.                                 |
| `cursor`  | `string`  | Cursor value for the next page. Pass the cursor from the previous response as is. |

- `cursor` is returned only when `hasMore` is `true`. The total count of the list is not returned.
- Lists whose `limit` range or default is different, lists without `limit`, lists that return all items, and lists that cannot be continued (where `hasMore` means something different) are described in each endpoint.

## Projects

A project is a unit for running work by placing Agents in steps. There are two types: `workflow` (steps run in order) and `cycle` (each placement keeps running in sweeps). The type is decided when the project is created and cannot be changed later.

### Endpoint List

| メソッド   | エンドポイント                                        | 説明                                                    | Scope (SaaS)     |
| ------ | ---------------------------------------------- | ----------------------------------------------------- | ---------------- |
| GET    | `/v1/projects`                                 | List the projects you participate in                  | `project:read`   |
| GET    | `/v1/projects/shared`                          | List shared projects                                  | `project:read`   |
| GET    | `/v1/projects/organizations`                   | Get the organizations you can set on a project        | `project:read`   |
| GET    | `/v1/projects/{projectId}`                     | Get a project                                         | `project:read`   |
| POST   | `/v1/projects`                                 | Create a project                                      | `project:write`  |
| PATCH  | `/v1/projects/{projectId}`                     | Edit a project                                        | `project:write`  |
| DELETE | `/v1/projects/{projectId}`                     | Delete a project                                      | `project:delete` |
| GET    | `/v1/projects/{projectId}/control`             | Get the control settings                              | `project:read`   |
| GET    | `/v1/projects/automation-destinations`         | List the destinations of external automation          | `project:read`   |
| GET    | `/v1/projects/{projectId}/definition`          | Export the definition of a project                    | `project:read`   |
| POST   | `/v1/projects/import`                          | Create a project from an exported definition (import) | `project:write`  |
| DELETE | `/v1/projects/{projectId}/relink`              | Clear the relink items to set up again if needed      | `project:write`  |
| GET    | `/v1/projects/{projectId}/definition-approval` | Get the pending definition approval                   | `project:read`   |
| DELETE | `/v1/projects/{projectId}/definition-approval` | Withdraw the pending definition change                | `project:write`  |

### GET`/v1/projects`

Retrieves the list of projects you take part in (projects you can read through the organization operations role are not listed).<!-- --> Supports cursor-based pagination. `cycle` projects also appear in the list, but they are not valid targets for starting a run (`POST /v1/projects/{projectId}/runs`).

#### Query Parameters

| Parameter | Type      | Default | Description                                                                                                                                 |
| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | `50`    | Number of items to retrieve (1-100)                                                                                                         |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                                                                      |
| `my_role` | `string`  | `—`     | One of "owner", "operator" or "member". Returns only the projects where the caller has that role (the earlier name myRole is also accepted) |

Any other query parameter is ignored.<!-- --> A value other than "owner" / "operator" / "member", specifying my\_role more than once, or giving different values to my\_role and myRole returns 400 Bad Request.

`cursor` represents a position, so do not change `my_role` while reusing the same cursor. Changing the criteria changes the result set and can duplicate or skip items.

<!-- -->

#### Request Example

**List projects**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                  | Type      | Description                                                                                            |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `projects`             | `array`   | Array of project objects                                                                               |
| `projects[].projectId` | `string`  | Project ID (UUID)                                                                                      |
| `projects[].name`      | `string`  | Project name                                                                                           |
| `projects[].type`      | `string`  | "workflow" or "cycle"                                                                                  |
| `projects[].status`    | `string`  | Project state. One of "active", "paused", "archived" or "admin\_stopped" (stopped by an administrator) |
| `projects[].tags`      | `array`   | Array of tags. An empty array when none are set                                                        |
| `projects[].myRole`    | `string`  | The caller's own role in that project: "owner", "operator" or "member"                                 |
| `projects[].owners`    | `array`   | User IDs of the project's current owners. Participants who are not owners are not included             |
| `hasMore`              | `boolean` | Whether a next page exists                                                                             |
| `cursor`               | `string`  | Cursor for the next page. Included only when hasMore is true                                           |

#### Response Example

<!-- -->

<!-- -->

```json
{
  "projects": [
    {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Order processing flow",
      "type": "workflow",
      "status": "active",
      "tags": [],
      "myRole": "owner",
      "owners": ["bbbe4306-6975-420b-af47-fb4c8f48b4aa"]
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Always-on inquiry handling",
      "type": "cycle",
      "status": "active",
      "tags": [],
      "myRole": "member",
      "owners": ["90b40fd8-a6b8-42b8-ab61-f3b674169b43", "463e2c25-5a80-4362-b77e-941df96fb1f2"]
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                                                                           |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | limit is outside 1-100, or cursor or my\_role is invalid (code is invalid\_parameter) |
| `403`  | The project:read scope is missing (code is insufficient\_scope)                       |

### GET`/v1/projects/shared`

Lists shared projects (your own projects are included if they are shared). A project shared only with organizations is listed only for users in those organizations. Cursor-based pagination is supported.

#### Query Parameters

| Parameter | Type      | Default     | Description                                                                                                                           |
| --------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | `50`        | Number of items per page (1-100)                                                                                                      |
| `cursor`  | `string`  | `—`         | Cursor for the next page (the cursor value from the previous response)                                                                |
| `type`    | `string`  | `—`         | Filter by "cycle" or "workflow"                                                                                                       |
| `tag`     | `string`  | `—`         | Filter to projects with this tag (up to 30 characters, not counting leading and trailing whitespace or a leading #; case-insensitive) |
| `q`       | `string`  | `—`         | Filter by part of the name or description (up to 100 characters)                                                                      |
| `sort`    | `string`  | `"popular"` | Sort order. "popular" is by the number of copies (then by update time, newest first), and "new" is by update time, newest first       |

#### Request Example

**List shared projects**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared?type=workflow&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared",
  headers={"Authorization": f"Bearer {token}"},
  params={"type": "workflow", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared" + "?type=workflow&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/shared?type=workflow&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                           | Type             | Description                                                                                            |
| ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `projects`                      | `array`          | Array of projects                                                                                      |
| `projects[].projectId`          | `string`         | Project ID (UUID)                                                                                      |
| `projects[].name`               | `string \| null` | Project name                                                                                           |
| `projects[].description`        | `string \| null` | Description                                                                                            |
| `projects[].type`               | `string \| null` | "workflow" or "cycle"                                                                                  |
| `projects[].status`             | `string \| null` | One of "active", "paused", "archived", or "admin\_stopped" (stopped by an administrator)               |
| `projects[].tags`               | `array`          | Array of tags                                                                                          |
| `projects[].shareScope`         | `string \| null` | Who the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations) |
| `projects[].shareOrganizations` | `array \| null`  | Array of the organization codes it is shared with. Used when shareScope is "organizations"             |
| `projects[].stepCount`          | `number \| null` | Number of enabled steps                                                                                |
| `projects[].agentCount`         | `number \| null` | Number of placements                                                                                   |
| `projects[].copyCount`          | `number \| null` | Number of times copied                                                                                 |
| `projects[].connectorCount`     | `number \| null` | Number of connectors                                                                                   |
| `projects[].ownerUserId`        | `string \| null` | User ID of the owner                                                                                   |
| `projects[].updatedAt`          | `string \| null` | Last updated time (ISO 8601)                                                                           |
| `hasMore`                       | `boolean`        | Whether there is a next page                                                                           |
| `cursor`                        | `string`         | Cursor for the next page. Included only when hasMore is true                                           |

`myRole` and `owners` are not included, even for projects you are a member of.

#### Response Example

```json
{
  "projects": [
    {
      "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
      "name": "Invoice reconciliation",
      "description": "Matches invoice amounts against line items and turns differences into work items",
      "type": "workflow",
      "status": "active",
      "tags": [
        "Accounting"
      ],
      "shareScope": "all",
      "shareOrganizations": null,
      "stepCount": 3,
      "agentCount": 2,
      "copyCount": 5,
      "connectorCount": 0,
      "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "updatedAt": "2026-11-18T01:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                               |
| ------ | -------------------- | --------------------------------------------------------- |
| `400`  | `invalid_parameter`  | An invalid value for limit, cursor, type, tag, q, or sort |
| `403`  | `insufficient_scope` | The project:read scope is missing                         |
| `403`  | `forbidden`          | Called with a system integration token                    |
| `403`  | `sso_required`       | The user does not sign in with SSO                        |

### GET`/v1/projects/organizations`

Gets the organizations you can set when creating a project. Only the organization the calling user currently belongs to can be set (zero or one item). This differs from `GET /v1/organizations`, which returns all organizations.

#### Request Example

**Get project organizations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/organizations", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                   | Type             | Description                                                       |
| ----------------------- | ---------------- | ----------------------------------------------------------------- |
| `organizations`         | `array`          | Array of organizations                                            |
| `organizations[].value` | `string`         | Organization code (specify this in organizationCode of a project) |
| `organizations[].label` | `string \| null` | Organization name                                                 |
| `hasMore`               | `boolean`        | Always false                                                      |

#### Response Example

```json
{
  "organizations": [
    {
      "value": "eng",
      "label": "Engineering"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                       | Description                                                                         |
| ------ | -------------------------- | ----------------------------------------------------------------------------------- |
| `403`  | `insufficient_scope`       | The project:read scope is missing                                                   |
| `403`  | `forbidden`                | Called with a system integration token                                              |
| `403`  | `sso_required`             | The user does not sign in with SSO                                                  |
| `503`  | `organization_unavailable` | The organization the user belongs to cannot be confirmed (resend the request later) |

### GET`/v1/projects/automation-destinations`

Gets the list of destinations that can be set for external automation steps (`defaultZone` is `"automation"`). Destinations are registered by an administrator in the admin console; specify a `destinationId` returned here in `automationConfig.destinationId` of a step. The URLs and keys of destinations are not returned. Up to 500 are returned, in order of name.

#### Request Example

**List automation destinations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/automation-destinations", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                          | Type             | Description                                                                                                                                                                                      |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `destinations`                 | `array`          | Array of destinations (in order of name, up to 500)                                                                                                                                              |
| `destinations[].destinationId` | `string`         | ID of the destination (UUID)                                                                                                                                                                     |
| `destinations[].name`          | `string \| null` | Name of the destination                                                                                                                                                                          |
| `destinations[].active`        | `boolean`        | Whether it is active. A step that specifies an inactive destination cannot be saved, and runs cannot start                                                                                       |
| `dlpEnabled`                   | `boolean`        | Whether “DLP Integration” in the admin console is on (anything other than Off). Also true when the setting cannot be read. While true, external automation steps cannot be saved, enabled or run |
| `hasMore`                      | `boolean`        | Always false (destinations beyond 500 are not returned)                                                                                                                                          |

#### Response Example

```json
{
  "destinations": [
    {
      "destinationId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e",
      "name": "Expense reporting system",
      "active": true
    }
  ],
  "dlpEnabled": false,
  "hasMore": false
}
```

#### Error Responses

| Status | code                                  | Description                                                                                                                                     |
| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | `insufficient_scope`                  | The project:read scope is missing                                                                                                               |
| `403`  | `forbidden`                           | Called with a system integration token                                                                                                          |
| `403`  | `sso_required`                        | The user does not sign in with SSO                                                                                                              |
| `409`  | `automation_destinations_unavailable` | Destinations for external automation are not available in this environment. Ask an administrator to set up destinations for external automation |

### GET`/v1/projects/{projectId}`

Gets a project together with its steps, members, placements, triggers, notifications, and connectors. If a user who is not a member specifies a shared project, only the structure (a preview) is returned. A person with the organization operations role for the project's organization can read all of it, not a preview, even without taking part in the project (`myRole` is null and `orgOperator` is true).

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                                                                                                            |
| ------------ | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `definition` | `string` | —  | With "pending", returns the view with the pending definition change laid over it (the approved definition if nothing is pending). Without it, returns the approved definition |

#### Request Example

**Get project**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                              | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`                          | `object`          | The project (the table below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `steps`                            | `array`           | Array of steps (in order). See "Step Fields" for the fields of an item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `stepsDigest`                      | `string`          | A value for the order of the steps. Send it as baseDigest when reordering steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `members`                          | `array`           | Array of members                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `members[].userId`                 | `string`          | User ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `members[].role`                   | `string \| null`  | "owner", "operator" or "member"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `members[].joinedAt`               | `string \| null`  | When the user became a member (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `members[].name`                   | `string \| null`  | User name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `members[].email`                  | `string \| null`  | User email address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `placements`                       | `array`           | Array of placements. See "Placement Fields" for the fields of an item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `triggers`                         | `array`           | Array of triggers (time and webhook triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `triggers[].triggerId`             | `string \| null`  | Trigger ID (UUID). Used to fire, change, and delete the trigger                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `triggers[].type`                  | `string`          | "cron" (time) or "webhook"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `triggers[].name`                  | `string \| null`  | Name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `triggers[].enabled`               | `boolean \| null` | Whether it is enabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `triggers[].lastFiredAt`           | `string \| null`  | When it last fired (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `triggers[].nextFireAt`            | `string \| null`  | When it is scheduled to fire next (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `triggers[].createdAt`             | `string \| null`  | Creation time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `triggers[].cron`                  | `string \| null`  | Cron expression ("cron" triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `triggers[].timezone`              | `string \| null`  | Time zone ("cron" triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `triggers[].startStepId`           | `string \| null`  | ID of the step to start from ("cron" triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `triggers[].placementId`           | `string \| null`  | ID of the placement to start ("webhook" triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `triggers[].stepId`                | `string \| null`  | ID of the step to start ("webhook" triggers only)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `triggers[].startFailure`          | `object \| null`  | Start failure ("cron" triggers only). Set only when a start failed; otherwise null. See "Reading start failures" below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `triggers[].startFailure.reason`   | `string \| null`  | Code of the reason the run could not start                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `triggers[].startFailure.since`    | `string \| null`  | When runs stopped starting for this reason (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `triggers[].digest`                | `string`          | The value to send as baseDigest when changing the trigger                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `stepStartFailures`                | `array`           | Start failures of runs that start at the time set on the first step. Only steps that could not start are included. See "Reading start failures" below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `stepStartFailures[].stepId`       | `string \| null`  | Step ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `stepStartFailures[].reason`       | `string \| null`  | Code of the reason the run could not start                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `stepStartFailures[].since`        | `string \| null`  | When runs stopped starting for this reason (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `notifications`                    | `object`          | Notification settings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `notifications.gateReached`        | `boolean \| null` | Whether to notify when a review request arrives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `notifications.gateDueSoon`        | `boolean \| null` | Whether to send a reminder when a review request nears its deadline (null with an earlier version of the platform)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `notifications.gateOverdue`        | `boolean \| null` | Whether to notify when a review request passes its deadline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `notifications.runDeadlineOverdue` | `boolean \| null` | Whether to notify when a workflow run passes its deadline                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `notifications.runStalled`         | `boolean \| null` | Whether to notify when a workflow run stalls (makes no progress for limits.stallHours)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `connectors`                       | `array`           | Array of connectors registered to this project                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `connectors[].kind`                | `string \| null`  | "mcp" or "a2a"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `connectors[].connectionId`        | `string \| null`  | Connector ID. Read its contents with the connector API (GET /v1/connectors/{kind}/{connectionId}). Connectors that need no sign-in also have an ID. null for a connector disabled or deleted in the admin console, and when the connector information could not be checked                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `connectors[].name`                | `string \| null`  | Connector name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `connectors[].ledgerEnabled`       | `boolean \| null` | Whether the connector is used as a ledger                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `connectors[].confirmMode`         | `string \| null`  | Whether a person is asked to confirm before this connector is used: "none" (not asked), "first\_per\_execution" (the first use in each execution), or "always" (every use). An A2A connector is always "none". The confirmation arrives as a review request (gateKind "connection"), and approving it relaunches the Agent. An approval applies, for "first\_per\_execution" in a workflow, to the later steps of the same workflow run, and for "always", only to the relaunched execution (including executions relaunched after it asks for confirmation again). A cycle has no workflow run boundary, so "first\_per\_execution" works the same as "always". Set in the UI                                                                        |
| `connectors[].confirmWaitMinutes`  | `number \| null`  | Maximum time to wait for that confirmation (minutes)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `connectors[].login`               | `string \| null`  | Sign-in status: "connected" (signed in), "reauth\_required" (must sign in again), "not\_connected" (not signed in), or "not\_required" (a connector that needs no sign-in). null when the status cannot be confirmed. Sign in on the screen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `connectors[].createdAt`           | `string \| null`  | Registration time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `definitionView`                   | `string \| null`  | Only with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `relink`                           | `object \| null`  | For a project imported from an exported definition, the references that were not found in this environment and must be reconnected. null if there are none                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `relink.items`                     | `array`           | Array of the references to reconnect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `relink.items[].kind`              | `string`          | Kind of the reference. "connector" (a connector that was not found) and "agent" (a registered agent that was not found) refuse to start or resume runs until reconnected. "connection", "playbook\_version", "automation\_destination", "approvers", "branch\_target", "external\_wait", "trigger", "library", "input\_files", "placement\_env", "lanes", "connection\_binding" and "input\_binding" are items to set up again if needed and do not refuse runs. "branch\_target" means that the lane steps of a branch step were not found, so the lanes and conditions were removed. "unavailable" means that something not available in this environment's version, or a time trigger of a cycle definition (what is "cron\_trigger"), was removed |
| `relink.items[].blocking`          | `boolean`         | If true, runs are refused to start or resume. Not present in rows whose kind is "unavailable"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `relink.items[].*`                 | `—`               | Depending on the kind of row, hint fields (agent, name, step, what, from, to, type, count, names and agents) are present. Only names, versions and counts; no IDs or URLs. names holds only the names of environment variables, not their values                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

A member (`member`) can also start workflow runs, fire webhook triggers<!-- --> and cancel workflow runs they started. An operator (`operator`) can, in addition, cancel workflow runs others started, set workflow run deadlines, reassign reviewers<!-- -->, resume closed workflow runs, rerun failed sweeps<!-- -->, and pause or resume the project (changing `status` alone). Project settings, steps, agent placements, triggers, webhooks, sharing and deletion<!-- --> are for owners only<!-- -->. People with the organization operations role can also call the operator operations without taking part in the project. A member without the organization operations role calling an operator operation gets `403 Forbidden` (`operator_only`).

Fields of `project`:

| Field                        | Type              | Description                                                                                                                                                                                |
| ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `projectId`                  | `string`          | Project ID (UUID)                                                                                                                                                                          |
| `name`                       | `string \| null`  | Project name                                                                                                                                                                               |
| `description`                | `string \| null`  | Description                                                                                                                                                                                |
| `tags`                       | `array`           | Array of tags                                                                                                                                                                              |
| `type`                       | `string \| null`  | "workflow" or "cycle"                                                                                                                                                                      |
| `status`                     | `string \| null`  | One of "active" (active), "paused" (paused), "archived" (archived), or "admin\_stopped" (stopped by an administrator)                                                                      |
| `adminStop`                  | `object \| null`  | When an administrator has stopped the project: where it was stopped from, why, and when. null if it is not stopped. Returned only by Get Project                                           |
| `adminStop.source`           | `string \| null`  | Where it was stopped from. "aster" (an AGENTIC STAR administrator), or a connected service: "agent365" or "aws"                                                                            |
| `adminStop.reasonCode`       | `string \| null`  | The kind of reason. "admin" (an administrator stopped it), "remote\_stopped" (it was stopped in the connected service), or "remote\_unreachable" (the connected service cannot be reached) |
| `adminStop.reason`           | `string \| null`  | The reason text. null if there is none                                                                                                                                                     |
| `adminStop.stoppedAt`        | `string \| null`  | When it was stopped (ISO 8601)                                                                                                                                                             |
| `policy`                     | `object \| null`  | Execution rules. Returned as set on the screen. Cannot be changed with this API                                                                                                            |
| `limits`                     | `object \| null`  | Execution limits                                                                                                                                                                           |
| `limits.maxRetriesPerStep`   | `number`          | Maximum number of retries when a step fails                                                                                                                                                |
| `limits.maxSendBacksPerStep` | `number`          | Maximum number of times work can be sent back to the same step                                                                                                                             |
| `limits.runDeadlineHours`    | `number \| null`  | Default deadline of a workflow run (hours from its start). No deadline is set if null or absent                                                                                            |
| `limits.stallHours`          | `number`          | Hours without progress after which a run is treated as stalled (24 if absent)                                                                                                              |
| `limits.maxMinutesPerRun`    | `number \| null`  | Maximum length of one execution (minutes): 5, 15, 30, 60, 90, or 120. When absent or null, this limit is not set                                                                           |
| `language`                   | `string \| null`  | Language of the project                                                                                                                                                                    |
| `flowStructure`              | `object \| null`  | Lane definition (for a workflow that runs steps in parallel). See "Lane Definition" below                                                                                                  |
| `reportTargets`              | `object \| null`  | Not used at present (even if it has a value, the value is not used)                                                                                                                        |
| `escalateToUserId`           | `string \| null`  | User ID of the default contact of the project (the contact for overdue review requests. Cannot be changed with this endpoint)                                                              |
| `organizationCode`           | `string \| null`  | Organization code                                                                                                                                                                          |
| `organizationName`           | `string \| null`  | Organization name                                                                                                                                                                          |
| `isShared`                   | `boolean \| null` | Whether it is shared                                                                                                                                                                       |
| `shareScope`                 | `string \| null`  | Who the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)                                                                                     |
| `shareOrganizations`         | `array \| null`   | Array of the organization codes it is shared with. Used when shareScope is "organizations"                                                                                                 |
| `copyCount`                  | `number \| null`  | Number of times copied                                                                                                                                                                     |
| `ownerUserId`                | `string \| null`  | User ID of the owner                                                                                                                                                                       |
| `myRole`                     | `string \| null`  | Role of the calling user: "owner", "operator" or "member". null in a preview and for a person with the organization operations role who does not take part in the project                  |
| `orgOperator`                | `boolean`         | Whether the calling user has the organization operations role for the project's organization. Returned only by Get Project (not in the list)                                               |
| `createdAt`                  | `string \| null`  | Creation time (ISO 8601)                                                                                                                                                                   |
| `updatedAt`                  | `string \| null`  | Last updated time (ISO 8601)                                                                                                                                                               |
| `digest`                     | `string`          | The value to send as baseDigest when editing the project                                                                                                                                   |

Lane definition (`flowStructure`):

| Field                  | Type             | Description                                                                                 |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `lanes`                | `array`          | Array of lanes                                                                              |
| `lanes[].id`           | `string \| null` | Lane ID                                                                                     |
| `lanes[].name`         | `string \| null` | Lane name                                                                                   |
| `lanes[].parentLaneId` | `string \| null` | ID of the lane before the split                                                             |
| `lanes[].stepIds`      | `array`          | Array of IDs of the steps in this lane. Steps that belong to no lane are in the "main" lane |
| `forks`                | `array`          | Array of splits                                                                             |
| `forks[].id`           | `string \| null` | Split ID                                                                                    |
| `forks[].afterStepId`  | `string \| null` | The split happens after this step                                                           |
| `forks[].laneIds`      | `array`          | Array of IDs of the lanes after the split                                                   |
| `forks[].joinId`       | `string \| null` | ID of the join                                                                              |
| `joins`                | `array`          | Array of joins                                                                              |
| `joins[].id`           | `string \| null` | Join ID                                                                                     |
| `joins[].mode`         | `string \| null` | "and" (proceeds when all lanes are complete)                                                |
| `joins[].laneIds`      | `array`          | Array of IDs of the lanes that join                                                         |
| `joins[].nextStepId`   | `string \| null` | ID of the step to proceed to after the join                                                 |

Reading start failures (`triggers[].startFailure` and `stepStartFailures`):

These record times when a workflow run could not start on schedule. There are two kinds: time triggers (`"cron"`) and the time set on the first step (the step's `schedule`).

- A value is set only when the last start record in the past 90 days for that trigger (step) is a failure. After a successful start, and before the time has ever come, `startFailure` is null and the step is not in `stepStartFailures`.
- While the same reason continues, only the first occurrence is recorded. `since` is when runs stopped starting for that reason, and it changes when the reason changes. If runs have not started for the same reason for more than 90 days, the record is older than 90 days, so the value is null (not included).
- A start skipped for a reason that is not recorded, such as the project being paused or the limit on concurrent runs being reached, does not change the value (a previous failure stays a failure, and null stays null after a successful start).
- Runs start at the time set on the first step only when there is no enabled time trigger. While an enabled time trigger exists, `stepStartFailures` shows earlier records. It can also include the ID of a deleted step.

Main values of `reason`. Other values can also be returned.

| Value                   | Meaning                                                   |
| ----------------------- | --------------------------------------------------------- |
| `approvers_required`    | A human review step has no reviewer who is still a member |
| `start_step_after_fork` | The step to start from is after the fork (inside a lane)  |
| `unsupported_runtime`   | An Agent of a kind this service cannot run is placed      |
| `unexpected_error`      | An unexpected failure                                     |

When a user who is neither a member nor a person with the organization operations role reads a shared project (a preview), `project` (without `organizationName`, `digest`, and `adminStop`; `myRole` is null), `steps` (without the `digest` of each step), and `placements` (only `placementId`, `agentId`, `name`, `description`, `goal`, `stepIds`, and `skillCount`) are returned. `stepsDigest`, `members`, `triggers`, `stepStartFailures`, `notifications`, `connectors`, and `relink` are not returned.

The `goal`, `guardrail`, and `inputFiles` (file names) of placed Agents are returned even without the `assets:read` scope.

#### Response Example

```json
{
  "project": {
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "name": "Invoice reconciliation",
    "description": "Matches invoice amounts against line items and turns differences into work items",
    "tags": [
      "Accounting"
    ],
    "type": "workflow",
    "status": "active",
    "policy": {
      "profile": "open",
      "deny": []
    },
    "limits": {
      "maxRetriesPerStep": 2,
      "maxSendBacksPerStep": 3,
      "runDeadlineHours": null,
      "stallHours": 24,
      "maxMinutesPerRun": null
    },
    "language": "ja",
    "flowStructure": null,
    "reportTargets": {
      "app": true
    },
    "escalateToUserId": null,
    "organizationCode": "eng",
    "isShared": false,
    "shareScope": null,
    "shareOrganizations": null,
    "copyCount": 0,
    "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "myRole": "owner",
    "createdAt": "2026-11-10T09:00:00.000Z",
    "updatedAt": "2026-11-18T01:00:00.000Z",
    "organizationName": "Engineering",
    "digest": "nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ",
    "adminStop": null,
    "orgOperator": false,
    "relink": null
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "Amount check",
      "description": "Matches invoice amounts against line items",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "Difference check",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "Difference report",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
    }
  ],
  "stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
  "members": [
    {
      "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "role": "owner",
      "joinedAt": "2026-11-10T09:00:00.000Z",
      "name": "Taro Tanaka",
      "email": "tanaka@example.com"
    }
  ],
  "placements": [
    {
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
      "displayOrder": 0,
      "name": "Accounting Agent",
      "description": "Matches invoice amounts against line items",
      "goal": "Match invoice amounts against line items and report differences",
      "guardrail": "Do not change amounts",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "Invoice reading"
        }
      ],
      "skillCount": 1,
      "playbookId": null,
      "playbookName": null,
      "inputFiles": [],
      "stepIds": [
        "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
      ],
      "sweeps": [],
      "runtimeConfigs": [
        {
          "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "runtimeConfig": null
        }
      ],
      "libraryBindings": [],
      "memoryOrgId": null,
      "memoryJobId": null,
      "instructionAddendum": null,
      "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "isShared": false,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "exclusiveToThisProject": true,
      "agentStopped": false,
      "relink": null,
      "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
    }
  ],
  "triggers": [],
  "stepStartFailures": [],
  "notifications": {
    "gateReached": true,
    "gateDueSoon": true,
    "gateOverdue": true,
    "runDeadlineOverdue": true,
    "runStalled": true
  },
  "connectors": []
}
```

#### Error Responses

| Status | code                 | Description                                                                                   |
| ------ | -------------------- | --------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                                                                       |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                             |
| `403`  | `forbidden`          | Called with a system integration token                                                        |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                            |
| `404`  | `project_not_found`  | The project does not exist, or it is a project that is not shared and you are not a member of |

### GET`/v1/projects/{projectId}/definition`

Returns the confirmed (approved) definition of a project as the same JSON as "Export definition" on the screen. Only owners can call it. The returned `definition` can be used as is in the body of the import (`POST /v1/projects/import`). It cannot be called with a system integration token.

- `definition` is returned in the export format of the product (`format` is `"agentic-star.project-definition"`, with a format version). The field names are not converted to camelCase.
- Reviewers, report destination addresses, connections, values of environment variables and the like are not included. However, the `agentConfig` of agents, the connection IDs in execution rules, and text written by users are included as is. If you put a secret in `agentConfig`, it is also in the export. In another environment, the same connection ID can point to something else. This response has `Cache-Control: no-store`.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Example

**Export project definition**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field        | Type     | Description                                                         |
| ------------ | -------- | ------------------------------------------------------------------- |
| `definition` | `object` | The definition of the project (in the export format of the product) |

#### Error Responses

| Status | code                 | Description                                                                           |
| ------ | -------------------- | ------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not in UUID format                                                       |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                     |
| `403`  | `forbidden`          | Called with a system integration token                                                |
| `403`  | `owner_only`         | A member who is not an owner                                                          |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                    |
| `404`  | `project_not_found`  | The project does not exist, you are not a member, or there is no confirmed definition |

### POST`/v1/projects/import`

Creates a project from an exported definition (the `definition` of `GET /v1/projects/{projectId}/definition`). Same as "Import from file" on the screen. Anyone who can create projects can call it (the caller becomes the owner). It cannot be called with a system integration token. `Idempotency-Key` is not accepted.

- The created project is paused (`status` is `"paused"`), and its time triggers and sweeps are disabled. Check it, then resume it.
- References that are not found in this environment (connectors, agents, playbooks, skills and so on) are not brought in and appear in `relink` of the response. While references that refuse runs remain, runs cannot start (`409`, `relink_required`).
- The `project` in the response is the project right after creation. Before changing the imported project, read it again with Get Project (`GET /v1/projects/{projectId}`) and send that `digest` as `baseDigest`.
- If no response came back (a timeout or a cut connection), the project may have been created. Check the list of projects (`GET /v1/projects`) before retrying.

#### Request Body

| Field              | Type             | Required | Description                                                                          |
| ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------ |
| `definition`       | `object`         | Required | The exported definition (the definition of the export response as is)                |
| `organizationCode` | `string \| null` | —        | Code of the organization. Same as organizationCode of the API that creates a project |

#### Response (201 Created)

| Field                      | Type             | Description                                                                                                                                                                                                                                       |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`                  | `object`         | The created project. Same fields as project in the response of the API that creates a project                                                                                                                                                     |
| `relink`                   | `object`         | References to reconnect                                                                                                                                                                                                                           |
| `relink.items`             | `array`          | Array of the references to reconnect. The fields of a row are the same as relink.items of Get Project                                                                                                                                             |
| `relink.agents`            | `array`          | For each placed agent, the playbooks and skills that were not found                                                                                                                                                                               |
| `relink.agents[].agent`    | `string`         | Name of the agent                                                                                                                                                                                                                                 |
| `relink.agents[].playbook` | `object \| null` | The playbook that was not found (name and versionNo)                                                                                                                                                                                              |
| `relink.agents[].skills`   | `array`          | Array of the skills that were not found (name and versionNo)                                                                                                                                                                                      |
| `definitionApproval`       | `object \| null` | When the tenant requires approval for definition changes, the first definition of the created project becomes pending and this holds its state (see [Definition approval fields](#definition-approval-object)). null when no approval is required |

#### Response Example

```json
{
  "project": {
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "name": "Invoice reconciliation",
    "description": "Matches invoice amounts against line items and turns differences into work items",
    "tags": [
      "Accounting"
    ],
    "type": "workflow",
    "status": "paused",
    "policy": {
      "profile": "open",
      "deny": []
    },
    "limits": {
      "maxRetriesPerStep": 2,
      "maxSendBacksPerStep": 3,
      "runDeadlineHours": null,
      "stallHours": 24,
      "maxMinutesPerRun": null
    },
    "language": "ja",
    "flowStructure": null,
    "reportTargets": {
      "app": true
    },
    "escalateToUserId": null,
    "organizationCode": "eng",
    "isShared": false,
    "shareScope": null,
    "shareOrganizations": null,
    "copyCount": 0,
    "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "myRole": "owner",
    "createdAt": "2026-11-10T09:00:00.000Z",
    "updatedAt": "2026-11-18T01:00:00.000Z",
    "digest": "_gJst28TCaZ7M6mBEeKgT4XIkVKFcsB0s8Kzdu9uisw"
  },
  "relink": {
    "items": [],
    "agents": []
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                        |
| ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | definition is not an object, or the type or length of organizationCode is wrong                                                                                                                                                                                                    |
| `400`  | `invalid_body`                    | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                    |
| `400`  | `invalid_definition_file`         | The shape of the definition is not valid                                                                                                                                                                                                                                           |
| `400`  | `unsupported_definition_version`  | The format version of the definition cannot be handled in this environment. Align the versions of the environment that exported it and the one that imports it                                                                                                                     |
| `400`  | `definition_too_large`            | The definition is too large (more than 200 operations to create). Make the definition smaller                                                                                                                                                                                      |
| `400`  | `organization_not_member`         | An organization that cannot be set was specified                                                                                                                                                                                                                                   |
| `400`  | `import_failed`                   | A write while creating the project was refused. error.message says which operation was refused and why (if the original failure was a 5xx, the same 5xx is returned)                                                                                                               |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                                                                                                                                                                                 |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                                                                                                                             |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                                                                                                                                 |
| `403`  | `feature_not_permitted`           | The definition has a trigger or a step with a schedule (any step), but an administrator has not permitted scheduled run creation (sweeps are always disabled on import, so they do not cause this). It is refused before anything is created, so no partly created project is left |
| `403`  | `license_status_unavailable`      | The license cannot be confirmed                                                                                                                                                                                                                                                    |
| `409`  | `project_limit_reached`           | The number of projects has reached the limit (the number is in error.message)                                                                                                                                                                                                      |
| `413`  | `body_too_large`                  | The body exceeds 3 MiB                                                                                                                                                                                                                                                             |
| `415`  | `unsupported_media_type`          | The Content-Type of the body is not application/json                                                                                                                                                                                                                               |
| `503`  | `feature_permissions_unavailable` | The feature permissions could not be checked. Retry after a while                                                                                                                                                                                                                  |
| `503`  | `approval_setting_unavailable`    | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                           |

### DELETE`/v1/projects/{projectId}/relink`

From the `relink` of an imported project, clears only the items to set up again if needed, which do not refuse runs (rows whose `blocking` is `false`; the same as "Mark as reviewed" on the screen). Only owners can call it. References that refuse runs (rows whose `blocking` is `true`) and the placements' `relink` (playbooks and skills that a placed agent points to and that were not found) remain. Clearing these alone does not let runs start. It cannot be called with a system integration token.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Example

**Dismiss project relink**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

```json
{
  "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  "dismissed": true
}
```

#### Error Responses

| Status | code                 | Description                                         |
| ------ | -------------------- | --------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not in UUID format                     |
| `403`  | `insufficient_scope` | The project:write scope is missing                  |
| `403`  | `forbidden`          | Called with a system integration token              |
| `403`  | `owner_only`         | A member who is not an owner                        |
| `403`  | `sso_required`       | The user does not sign in with SSO                  |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member |

### POST`/v1/projects`

Creates a project. The user who creates it becomes the owner and the principal that runs the project. <!-- -->Create Agents in the library first, and then place them<!-- --> with the API that places a placement (`POST /v1/projects/{projectId}/placements`).

#### Request Body

| Field                        | Type             | Required | Description                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                       | `string`         | Yes      | Project name (up to 255 characters; cannot be only whitespace)                                                                                                                                                                                                                                                             |
| `description`                | `string`         | —        | Description (up to 5000 characters)                                                                                                                                                                                                                                                                                        |
| `tags`                       | `array`          | —        | Tags (up to 10 strings of up to 30 characters each; saved in lowercase with leading and trailing whitespace and a leading # removed. Tags that become empty or the same this way cannot be sent)                                                                                                                           |
| `type`                       | `string`         | —        | "cycle" or "workflow". "cycle" if omitted                                                                                                                                                                                                                                                                                  |
| `organizationCode`           | `string \| null` | —        | Organization code (up to 255 characters). Only an organization returned by GET /v1/projects/organizations can be set. null, an empty string, or only whitespace is the same as not setting one                                                                                                                             |
| `steps`                      | `array`          | —        | The steps (up to 12). When a non-empty array is given, a workflow needs at least 2 steps and a cycle at least 1. If omitted or empty, the project is created with the default steps (for a workflow, three steps: a step run by an Agent, a review step, and a step run by an Agent; for a cycle, two steps run by Agents) |
| `steps[].name`               | `string \| null` | —        | Step name (up to 100 characters; an empty string or null means the default name; cannot be only whitespace)                                                                                                                                                                                                                |
| `steps[].description`        | `string \| null` | —        | Step description (an empty string or null means no description)                                                                                                                                                                                                                                                            |
| `steps[].enabled`            | `boolean`        | —        | Whether it is enabled (true or false). Enabled if omitted                                                                                                                                                                                                                                                                  |
| `steps[].zone`               | `string`         | —        | One of "ai" (run by an Agent), "gate" (review step) and "automation" (external automation). "ai" if omitted. Only "ai" for cycle. null cannot be sent                                                                                                                                                                      |
| `steps[].automationConfig`   | `object \| null` | —        | Settings of the external automation (only for a step whose zone is "automation"). Same shape as automationConfig in Step Fields. If omitted, the step is created without settings (they are needed before a run starts)                                                                                                    |
| `steps[].placementExecution` | `string \| null` | —        | "parallel" runs the Agents placed in the step at the same time ("ai" steps of a workflow only). If omitted, null, or "serial", they run one at a time                                                                                                                                                                      |
| `steps[].outputConfig`       | `object \| null` | —        | Values and file roles passed to the next step ("ai" steps of a workflow only). The shape and rules are the same as outputConfig in the step fields. Can be omitted                                                                                                                                                         |

`trigger`, `policy`, `agents`, `guardrail`, and `templateRef` are not accepted (sending them returns `400`, `invalid_parameter`). Set execution rules on the screen. Add triggers after creating the project, with the API that creates a trigger (`POST /v1/projects/{projectId}/triggers`). For a cycle, set the sweep interval after placing Agents, with the API that changes the sweep (`PATCH /v1/projects/{projectId}/placements/{placementId}/schedule`).

#### Request Example

**Create project**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Invoice reconciliation",
  "description": "Matches invoice amounts against line items and turns differences into work items",
  "tags": [
    "Accounting"
  ],
  "type": "workflow",
  "organizationCode": "eng"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': 'Invoice reconciliation', 'description': 'Matches invoice amounts against line items and turns differences into work items', 'tags': ['Accounting'], 'type': 'workflow', 'organizationCode': 'eng'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "Invoice reconciliation", "description": "Matches invoice amounts against line items and turns differences into work items", "tags": ["Accounting"], "type": "workflow", "organizationCode": "eng"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"name": "Invoice reconciliation", "description": "Matches invoice amounts against line items and turns differences into work items", "tags": ["Accounting"], "type": "workflow", "organizationCode": "eng"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (201 Created)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                                        |
| -------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`            | `object`         | The created project. Same fields as project in Get Project (without organizationName and adminStop; myRole is "owner")                                                                                                                                                                                                                             |
| `steps`              | `array`          | Array of the created steps. See "Step Fields" for the fields of an item                                                                                                                                                                                                                                                                            |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, the first definition of the created project becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs cannot start. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "project": {
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "name": "Invoice reconciliation",
    "description": "Matches invoice amounts against line items and turns differences into work items",
    "tags": [
      "Accounting"
    ],
    "type": "workflow",
    "status": "active",
    "policy": {
      "profile": "open",
      "deny": []
    },
    "limits": {
      "maxRetriesPerStep": 2,
      "maxSendBacksPerStep": 3,
      "runDeadlineHours": null,
      "stallHours": 24,
      "maxMinutesPerRun": null
    },
    "language": "ja",
    "flowStructure": null,
    "reportTargets": {
      "app": true
    },
    "escalateToUserId": null,
    "organizationCode": "eng",
    "isShared": false,
    "shareScope": null,
    "shareOrganizations": null,
    "copyCount": 0,
    "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "myRole": "owner",
    "createdAt": "2026-11-18T05:00:00.000Z",
    "updatedAt": "2026-11-18T05:00:00.000Z",
    "digest": "nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ"
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "rBZ_uP64l5OjdSlPVOdAoWThVePY0Rqei1BltLAcvQg"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": null,
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
    }
  ],
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                                  | Description                                                                                                                                                                                                                                                                                                    |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`                   | name is missing or only whitespace, a field has the wrong type, length, number of items, or value (including empty or duplicate tags), more than 12 steps or a non-empty steps array with fewer than the minimum (2 for workflow, 1 for cycle), or trigger, policy, agents, guardrail, or templateRef was sent |
| `400`  | `invalid_body`                        | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                |
| `400`  | `cycle_gate_not_allowed`              | A review step ("gate") was specified for a cycle                                                                                                                                                                                                                                                               |
| `400`  | `invalid_parameter`                   | The shape or a value of steps\[].automationConfig is wrong (error.param holds the name of the field in steps\[N].automationConfig)                                                                                                                                                                             |
| `400`  | `automation_body_invalid`             | The content of steps\[].automationConfig.body does not meet the rules (16 KiB, depth 16, names you can insert). error.param is steps, and which step is not returned                                                                                                                                           |
| `400`  | `automation_config_not_allowed`       | automationConfig was specified for a step whose zone is not "automation"                                                                                                                                                                                                                                       |
| `400`  | `cycle_automation_not_allowed`        | An external automation step ("automation") was specified for a cycle                                                                                                                                                                                                                                           |
| `400`  | `automation_destination_missing`      | The destination of the external automation step was not found. Set steps\[].automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations. If no destinations are listed, ask an administrator (which step is not returned)                                            |
| `400`  | `automation_destination_inactive`     | The destination of the external automation step is inactive. Ask an administrator to activate the destination, or set another active destination from GET /v1/projects/automation-destinations (which step is not returned)                                                                                    |
| `409`  | `automation_dlp_enabled`              | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration                                                                                                                                                                                 |
| `409`  | `automation_destinations_unavailable` | Destinations for external automation are not available in this environment. Ask an administrator to set up destinations for external automation                                                                                                                                                                |
| `400`  | `parallel_workflow_only`              | "parallel" for placementExecution was specified for a step of a cycle                                                                                                                                                                                                                                          |
| `400`  | `parallel_ai_only`                    | "parallel" for placementExecution was specified for a step that is not "ai"                                                                                                                                                                                                                                    |
| `400`  | `output_config_invalid`               | steps\[].outputConfig has a wrong shape, count or length, or a repeated name, or it was sent for a step that is not "ai" or for a cycle step (the rules are those of outputConfig in the step fields). error.param is steps, and which step is not returned                                                    |
| `400`  | `organization_not_member`             | An organization that cannot be set was specified                                                                                                                                                                                                                                                               |
| `403`  | `insufficient_scope`                  | The project:write scope is missing                                                                                                                                                                                                                                                                             |
| `403`  | `forbidden`                           | Called with a system integration token                                                                                                                                                                                                                                                                         |
| `403`  | `sso_required`                        | The user does not sign in with SSO                                                                                                                                                                                                                                                                             |
| `403`  | `license_status_unavailable`          | The license cannot be confirmed                                                                                                                                                                                                                                                                                |
| `409`  | `project_limit_reached`               | The number of projects has reached the limit (the numbers are in error.message)                                                                                                                                                                                                                                |
| `413`  | `body_too_large`                      | The body exceeds 3 MiB                                                                                                                                                                                                                                                                                         |
| `415`  | `unsupported_media_type`              | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                           |
| `503`  | `organization_unavailable`            | The organization the user belongs to cannot be confirmed                                                                                                                                                                                                                                                       |
| `503`  | `approval_setting_unavailable`        | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                       |

### PATCH`/v1/projects/{projectId}`

Edits a project. Only the fields you send are changed. Only owners can call this API, except that operators and people with the organization operations role can also pause or resume the project by sending only `baseDigest` and `status` (`"active"` or `"paused"`).

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

| Field                        | Type              | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`                 | `string`          | Yes      | project.digest from Get Project                                                                                                                                                                                                                                                                                                                                                                                  |
| `name`                       | `string`          | —        | Project name (up to 255 characters; cannot be empty or only whitespace)                                                                                                                                                                                                                                                                                                                                          |
| `description`                | `string`          | —        | Description (up to 5000 characters; cannot be an empty string, only whitespace, or null)                                                                                                                                                                                                                                                                                                                         |
| `tags`                       | `array`           | —        | Tags (same as when creating). Sending them replaces all tags                                                                                                                                                                                                                                                                                                                                                     |
| `status`                     | `string`          | —        | "active", "paused", or "archived"                                                                                                                                                                                                                                                                                                                                                                                |
| `isShared`                   | `boolean`         | —        | Whether to share it                                                                                                                                                                                                                                                                                                                                                                                              |
| `shareScope`                 | `string`          | —        | Who the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)                                                                                                                                                                                                                                                                                                           |
| `shareOrganizations`         | `array`           | —        | Organization codes it is shared with (up to 20, each up to 255 characters; surrounding whitespace is removed and duplicates are merged). Sending it replaces the whole list. At least one is required when the item is shared with the scope "organizations", and when it is sent together with shareScope "organizations"                                                                                       |
| `limits`                     | `object`          | —        | Execution limits. Only the fields you send are overlaid on the current values                                                                                                                                                                                                                                                                                                                                    |
| `limits.maxRetriesPerStep`   | `integer`         | —        | 0 to 10                                                                                                                                                                                                                                                                                                                                                                                                          |
| `limits.maxSendBacksPerStep` | `integer`         | —        | 1 to 10                                                                                                                                                                                                                                                                                                                                                                                                          |
| `limits.runDeadlineHours`    | `integer \| null` | —        | 1 to 2160. null sets no deadline                                                                                                                                                                                                                                                                                                                                                                                 |
| `limits.stallHours`          | `integer`         | —        | 1 to 720                                                                                                                                                                                                                                                                                                                                                                                                         |
| `limits.maxMinutesPerRun`    | `integer \| null` | —        | Maximum length of one execution (minutes): 5, 15, 30, 60, 90, or 120. null sets no limit                                                                                                                                                                                                                                                                                                                         |
| `flowStructure`              | `object \| null`  | —        | Lane definition (same form as in Get Project). Sending it replaces the whole definition. null removes the lanes                                                                                                                                                                                                                                                                                                  |
| `organizationCode`           | `string \| null`  | —        | Organization code (up to 255 characters). Can be set only once, on a project that has no organization yet. Sending the current value changes nothing (you can send back the value you got). Sending a different value to a project that already has an organization returns 409 (organization\_locked). null changes nothing if no organization is set yet, and returns 409 (organization\_locked) if one is set |

Send at least one field besides baseDigest. `type`, `policy`, and `connectSecret` are not accepted (sending them returns `400`, `invalid_parameter`).<!-- --> The type is decided when the project is created, and execution rules are changed on the screen.

Setting `status` to `"paused"` or `"archived"` stops new executions from starting. Sweeps and time-based starts stop, starting workflow runs and firing triggers are refused with `409 Conflict`, and "Start by email" is no longer accepted<!-- --> (a resend of a workflow run start with the same `Idempotency-Key` as an accepted one returns the result of the first request). Running executions are not stopped. A running workflow run waits without starting its next step (its `status` stays `"running"` or `"waiting_gate"`). <!-- -->Fires and emails<!-- --> accepted before the stop may still run after it. Setting it back to `"active"` resumes the starts that were held while the project was stopped.

While an administrator has stopped the project (`status` is `"admin_stopped"`), an edit that sends `status` and deleting the project are refused with `409 Conflict` (`admin_stopped`). Other fields, such as the name, can be changed. An administrator resumes the project.

These are the rules for sending `flowStructure`. If they are not met, `400` (`invalid_flow_structure`) is returned.

- Only workflow projects can have lanes. A project where a registered Agent of the Marketplace edition is placed cannot have lanes.
- IDs of lanes, forks, and joins are up to 64 letters, digits, `_`, and `-`. Step IDs are UUIDs. Lane names are up to 50 characters and cannot be only whitespace. The `"main"` lane cannot have a name (set it to null or omit it).
- The `parentLaneId` of the `"main"` lane is null, and the `parentLaneId` of the other lanes is `"main"` (a lane cannot branch further). Up to 11 lanes other than `"main"` (if you send 12, one of them is left without a step and the request fails with 400 Bad Request (`invalid_flow_structure`)).
- To use lanes, include exactly one fork and one join. The `laneIds` of the fork are all the lanes other than `"main"` (2 or more), and its `joinId` is the `id` of the join. The `laneIds` of the join are the same lanes as the fork, and its `mode` is `"and"`.
- The `afterStepId` of the fork is a step in `"main"`, and it cannot be a step whose `placementExecution` is `"parallel"`. The `nextStepId` of the join is a later step in `"main"`. When it is null, all the steps after the fork go into lanes.
- All the steps between the fork and the join go into lanes, and the other steps go into `"main"`. A step cannot be in two lanes. `lanes[].stepIds` can contain only steps of this project. Each lane has at least one step.
- The destinations and the send-back step of a review step, and the `"goto"` destinations of onDenied and onDegraded, can only be steps in the same lane. In `"main"`, they cannot cross between before the fork and after the join.
- If there are no lanes other than `"main"` and `forks` and `joins` are empty, it is the same as null (the lanes are removed).

#### Request Example

**Update project**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ",
  "status": "paused"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ', 'status': 'paused'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ", "status": "paused"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "nUiRyqGtf9j8JaITNnzbKLo90JxfBYjipU1OBoicHDQ", "status": "paused"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project`            | `object`         | The project after the edit. Same fields as project in Get Project (without organizationName and adminStop)                                                                                                                                                                                                                        |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "project": {
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "name": "Invoice reconciliation",
    "description": "Matches invoice amounts against line items and turns differences into work items",
    "tags": [
      "Accounting"
    ],
    "type": "workflow",
    "status": "paused",
    "policy": {
      "profile": "open",
      "deny": []
    },
    "limits": {
      "maxRetriesPerStep": 2,
      "maxSendBacksPerStep": 3,
      "runDeadlineHours": null,
      "stallHours": 24,
      "maxMinutesPerRun": null
    },
    "language": "ja",
    "flowStructure": null,
    "reportTargets": {
      "app": true
    },
    "escalateToUserId": null,
    "organizationCode": "eng",
    "isShared": false,
    "shareScope": null,
    "shareOrganizations": null,
    "copyCount": 0,
    "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "myRole": "owner",
    "createdAt": "2026-11-10T09:00:00.000Z",
    "updatedAt": "2026-11-18T05:30:00.000Z",
    "digest": "_gJst28TCaZ7M6mBEeKgT4XIkVKFcsB0s8Kzdu9uisw"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                                                                                                                                                                                                          |
| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`            | projectId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name was set empty or only whitespace, description was set to an empty string, only whitespace, or null, null was sent for name, status, tags, isShared, or limits, a field has the wrong type or value (including empty or duplicate tags), or type, policy, or connectSecret was sent |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                      |
| `400`  | `invalid_share_scope`          | shareScope is not "all" or "organizations"                                                                                                                                                                                                                                                                                                                                           |
| `400`  | `invalid_share_organizations`  | shareOrganizations is not an array, has 21 or more items, or has a value that is not a string, is empty or only whitespace, or is 256 characters or longer                                                                                                                                                                                                                           |
| `400`  | `share_organizations_required` | "organizations" was sent for shareScope with an empty shareOrganizations, or the item is shared (isShared is true in the sent or current value) while the scope is "organizations" and there is no organization (the sent and current values are combined)                                                                                                                           |
| `400`  | `invalid_flow_structure`       | The lane definition does not follow the rules above                                                                                                                                                                                                                                                                                                                                  |
| `400`  | `organization_not_member`      | An organization that cannot be set was specified                                                                                                                                                                                                                                                                                                                                     |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                                                                                                                                                                                                                   |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                                                                                                                                                                                                               |
| `403`  | `owner_only`                   | A member who is not an owner sent a change that sets status to "archived" or includes an updatable field (in the request body table above) other than status                                                                                                                                                                                                                         |
| `403`  | `operator_only`                | A member who is neither an owner nor an operator and does not have the organization operations role sent a change that only pauses or resumes the project                                                                                                                                                                                                                            |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                   |
| `404`  | `project_not_found`            | The project does not exist, or you are not a member                                                                                                                                                                                                                                                                                                                                  |
| `409`  | `stale_base`                   | The project has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest                                                                                                                                                                                    |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                                                                                             |
| `409`  | `relink_required`              | References missing after the import must be reconnected before the project can resume from a pause (status set to "active"). For how to fix it, see relink\_required in the error table of starting a workflow run                                                                                                                                                                   |
| `409`  | `admin_stopped`                | An administrator has stopped the project (its status cannot be changed)                                                                                                                                                                                                                                                                                                              |
| `409`  | `organization_locked`          | An organization is already set (a different value or null was sent)                                                                                                                                                                                                                                                                                                                  |
| `403`  | `license_status_unavailable`   | Tried to move the project out of "archived", but the license cannot be confirmed                                                                                                                                                                                                                                                                                                     |
| `409`  | `project_limit_reached`        | Tried to move the project out of "archived", but the number of projects has reached the limit                                                                                                                                                                                                                                                                                        |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                              |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                 |
| `503`  | `organization_unavailable`     | The organization the user belongs to cannot be confirmed                                                                                                                                                                                                                                                                                                                             |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                                                                                             |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                                                                                            |

### DELETE`/v1/projects/{projectId}`

Deletes a project. Only owners can call this API. What is running (sweeps, running workflow runs, review requests waiting for a decision, and triggers) stops. Records of executions and reviews are not deleted. The service also tries to remove sign-ins to the project's connectors, but the deletion of the project succeeds even if they cannot be removed.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Example

**Delete project**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

```json
{
  "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
  "deleted": true
}
```

Calling it again returns `404 Not Found`.

#### Error Responses

| Status | code                 | Description                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId is not a UUID                                                                          |
| `403`  | `insufficient_scope` | The project:delete scope is missing                                                              |
| `403`  | `forbidden`          | Called with a system integration token                                                           |
| `403`  | `owner_only`         | A member who is not an owner                                                                     |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                               |
| `404`  | `project_not_found`  | The project does not exist, you are not a member, or it has already been deleted                 |
| `409`  | `legal_hold`         | The project is under legal hold. It cannot be deleted until an administrator releases the hold   |
| `409`  | `admin_stopped`      | An administrator has stopped the project. It cannot be deleted until an administrator resumes it |

### GET`/v1/projects/{projectId}/control`

Gets the control settings of a project (the strength of the execution rules and the settings of review steps).

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                                                            |
| ------------ | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------- |
| `definition` | `string` | —  | With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition |

#### Request Example

**Get project control**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                     | Type             | Description                                                                                                                                                                                          |
| ------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tenantProfile`           | `string \| null` | Base rule for the whole tenant: "open", "guarded", or "strict". null when it cannot be confirmed                                                                                                     |
| `tenantSource`            | `string \| null` | Where tenantProfile comes from: "governance\_policies" (set in the admin console), "default" (no setting, so the default), or "unavailable" (cannot be confirmed)                                    |
| `projectProfile`          | `string \| null` | Base rule of this project                                                                                                                                                                            |
| `effectiveProfile`        | `string \| null` | The base rule actually in effect (the stricter of the tenant and this project). null when tenantProfile is null                                                                                      |
| `deny`                    | `array`          | Operations prohibited by the execution rules                                                                                                                                                         |
| `gates`                   | `array`          | Array of enabled review steps                                                                                                                                                                        |
| `gates[].stepId`          | `string`         | Step ID                                                                                                                                                                                              |
| `gates[].position`        | `number`         | Position of the step                                                                                                                                                                                 |
| `gates[].name`            | `string`         | Step name                                                                                                                                                                                            |
| `gates[].gateKind`        | `string`         | Kind of review: "review" (review) or "manual" (manual work)                                                                                                                                          |
| `gates[].mode`            | `string`         | Review method: "blocking" (wait for the reviewer's decision) or "notify\_only" (proceed automatically after the deadline)                                                                            |
| `gates[].overdueAction`   | `string`         | After the deadline: "none" (notify and keep waiting), "proceed" (proceed automatically), "send\_back" (send back automatically), or "reject" (reject automatically)                                  |
| `gates[].approverUserIds` | `array`          | Array of user IDs of the reviewers                                                                                                                                                                   |
| `gates[].deadlineHours`   | `number \| null` | Deadline (hours)                                                                                                                                                                                     |
| `operationClasses`        | `null`           | Not used at present (always null)                                                                                                                                                                    |
| `definitionView`          | `string \| null` | Only with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined |

#### Response Example

```json
{
  "tenantProfile": "guarded",
  "tenantSource": "default",
  "projectProfile": "guarded",
  "effectiveProfile": "guarded",
  "deny": [],
  "gates": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 2,
      "name": "Amount check",
      "gateKind": "review",
      "mode": "blocking",
      "overdueAction": "none",
      "approverUserIds": [
        "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      ],
      "deadlineHours": 24
    }
  ],
  "operationClasses": null
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                     |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                                                                                                         |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                               |
| `403`  | `forbidden`          | Called with a system integration token                                                                                          |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                              |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                             |
| `409`  | `definition_invalid` | With definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason) |
| `503`  | `definition_busy`    | With definition=pending, another change to the same definition is in progress. Retry after a while                              |

### GET`/v1/projects/{projectId}/definition-approval`

Gets a summary of the definition change pending approval. Members can call it. When the tenant requires approval for definition changes, changes made by the write APIs (project, steps, placements, triggers and library bindings) become pending, and until they are approved, runs use the previous definition. Approving or sending back is done by an approver on the product screen (it cannot be decided with the API).

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Example

**Get definition approval**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                            | Type             | Description                                                                                                                                                                              |
| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `required`                       | `boolean`        | Whether the tenant requires approval for definition changes                                                                                                                              |
| `activeVersion`                  | `number \| null` | Number of the approved version of the definition (the one runs use)                                                                                                                      |
| `pending`                        | `object \| null` | The pending change. null if there is none. Same fields as pending in Definition approval fields below, plus createdAt and changes                                                        |
| `pending.createdAt`              | `string \| null` | When the pending change was created (ISO 8601)                                                                                                                                           |
| `pending.changes`                | `array`          | Array of what changes from the approved definition                                                                                                                                       |
| `pending.changes[].section`      | `string`         | Kind of what changes. "project", "steps", "placements", "triggers", "notifications" or "connectors"                                                                                      |
| `pending.changes[].key`          | `string \| null` | Which one within that kind (the ID of a step, placement or trigger, the ID of a connector, or the event and channel of a notification). null for "project"                               |
| `pending.changes[].change`       | `string`         | "added", "removed" or "updated"                                                                                                                                                          |
| `pending.changes[].fields`       | `array`          | Hint names of the changed fields. These names belong to this summary only and do not match the field names of the read responses. Check the content with a read using definition=pending |
| `lastRejection`                  | `object \| null` | The last change that was sent back (null if a change was approved after it)                                                                                                              |
| `lastRejection.version`          | `number`         | Number of the version that was sent back                                                                                                                                                 |
| `lastRejection.reviewedByUserId` | `string \| null` | User ID of the person who sent it back                                                                                                                                                   |
| `lastRejection.reviewedAt`       | `string \| null` | When it was sent back (ISO 8601)                                                                                                                                                         |
| `lastRejection.reason`           | `string \| null` | Reason for sending it back                                                                                                                                                               |
| `approverRule`                   | `string`         | Rule for who can approve (same as Definition approval fields below)                                                                                                                      |
| `approvers`                      | `object`         | People who can approve                                                                                                                                                                   |
| `approvers.ownerUserIds`         | `array`          | Array of the user IDs of the owners who can approve (excluding the requesters)                                                                                                           |
| `approvers.orgAdminCount`        | `number`         | Number of organization administrators who can approve                                                                                                                                    |
| `approvers.available`            | `boolean`        | Whether there is someone who can approve it                                                                                                                                              |
| `canApprove`                     | `boolean`        | Whether the caller can approve it (approval is done on the product screen)                                                                                                               |
| `canWithdraw`                    | `boolean`        | Whether the caller can withdraw the pending change (owners)                                                                                                                              |

#### Definition approval fields

The fields of `definitionApproval` in the responses of the write APIs and of the API that withdraws a pending change.

| Field                        | Type              | Description                                                                                                                                                   |
| ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `required`                   | `boolean \| null` | Whether the tenant requires approval for definition changes. null in the response of withdrawing a pending change when the setting could not be confirmed     |
| `status`                     | `string`          | "pending" (a change is pending) or "none" (nothing is pending)                                                                                                |
| `activeVersion`              | `number \| null`  | Number of the approved version of the definition (the one runs use). null if there is none yet                                                                |
| `pending`                    | `object \| null`  | The pending change. null if there is none                                                                                                                     |
| `pending.version`            | `number`          | Number of the pending version                                                                                                                                 |
| `pending.digest`             | `string`          | Value of the pending change. Send it as pendingDigest when you withdraw the pending change (it differs from the digest of Get Project)                        |
| `pending.baseVersion`        | `number \| null`  | Number of the version the pending change was based on                                                                                                         |
| `pending.initial`            | `boolean`         | Whether the first definition of a created project is pending. While true, runs cannot start                                                                   |
| `pending.requestedByUserIds` | `array`           | Array of the user IDs of the people who requested the change (including those who laid further changes over the pending one)                                  |
| `pending.updatedAt`          | `string \| null`  | When the pending change last changed (ISO 8601)                                                                                                               |
| `pending.workItemId`         | `string \| null`  | ID of the approval request sent to the people who approve it (the ID of the Inbox row; it cannot be read with the review request API)                         |
| `approverRule`               | `string`          | Rule for who can approve. "owner\_or\_org\_admin\_not\_requester" (an owner of the project or an administrator of the organization, other than the requester) |
| `approversAvailable`         | `boolean`         | Whether there is someone who can approve it                                                                                                                   |

#### Response Example

```json
{
  "required": true,
  "activeVersion": 2,
  "pending": null,
  "lastRejection": null,
  "approverRule": "owner_or_org_admin_not_requester",
  "approvers": {
    "ownerUserIds": [
      "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    ],
    "orgAdminCount": 1,
    "available": true
  },
  "canApprove": false,
  "canWithdraw": false
}
```

#### Error Responses

| Status | code                           | Description                                                                                    |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId is not in UUID format                                                                |
| `403`  | `insufficient_scope`           | The project:read scope is missing                                                              |
| `403`  | `forbidden`                    | Called with a system integration token                                                         |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                             |
| `404`  | `project_not_found`            | The project does not exist, or you are not a member                                            |
| `409`  | `forbidden_role`               | Called by a person with the organization operations role who does not take part in the project |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                       |

### DELETE`/v1/projects/{projectId}/definition-approval`

Withdraws the definition change pending approval. Owners can call it. The pending change is discarded, and the approved definition stays.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Query Parameters

| パラメータ           | 型        | 必須 | 説明                                                                                                                                                    |
| --------------- | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pendingDigest` | `string` | 必須 | Value of the pending change to withdraw (pending.digest in the response of a write API or of this summary). It differs from the digest of Get Project |

#### Request Example

**Withdraw definition approval**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval",
  headers={"Authorization": f"Bearer {token}"},
  params={"pendingDigest": "c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval" + "?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                | Type     | Description                                                                                 |
| -------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `definitionApproval` | `object` | The state after withdrawing (see [Definition approval fields](#definition-approval-object)) |

#### Response Example

```json
{
  "definitionApproval": {
    "required": true,
    "status": "none",
    "activeVersion": 2,
    "pending": null,
    "approverRule": "owner_or_org_admin_not_requester",
    "approversAvailable": true
  }
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                       |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not in UUID format, or pendingDigest is missing or malformed                                                         |
| `403`  | `insufficient_scope` | The project:write scope is missing                                                                                                |
| `403`  | `forbidden`          | Called with a system integration token                                                                                            |
| `403`  | `owner_only`         | A member who is not an owner                                                                                                      |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                                |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                               |
| `409`  | `no_pending`         | Nothing is pending. Read the summary again before deciding                                                                        |
| `409`  | `approval_stale`     | pendingDigest differs from the current pending change (further changes were laid over it). Read the summary again before deciding |
| `503`  | `definition_busy`    | Another change to the same definition is in progress. Retry after a while                                                         |

## Steps

A step is a unit of the project's flow. There are steps run by Agents (`defaultZone` is `"ai"`) and review steps decided by people (`"gate"`).<!-- --> There are also external automation steps that send a body to a destination you choose (`"automation"`; they hold no Agent).<!-- --> There are also branch steps (`"branch"`; they hold no Agent) that choose the lane to go to from the result of the previous step. A project can have up to 12 steps. You cannot delete steps to leave fewer than the minimum (2 for a workflow, 1 for a cycle).

### Endpoint List

| メソッド   | エンドポイント                                   | 説明            | Scope (SaaS)    |
| ------ | ----------------------------------------- | ------------- | --------------- |
| POST   | `/v1/projects/{projectId}/steps`          | Add a step    | `project:write` |
| PATCH  | `/v1/projects/{projectId}/steps/{stepId}` | Edit a step   | `project:write` |
| PUT    | `/v1/projects/{projectId}/steps/order`    | Reorder steps | `project:write` |
| DELETE | `/v1/projects/{projectId}/steps/{stepId}` | Delete a step | `project:write` |

### Step Fields

The fields of a step in `steps` of Get Project and in the responses of the step APIs.

| Field                             | Type              | Description                                                                                                                                                                                                             |
| --------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stepId`                          | `string`          | Step ID (UUID)                                                                                                                                                                                                          |
| `position`                        | `number \| null`  | Position of the step (from 1)                                                                                                                                                                                           |
| `name`                            | `string \| null`  | Step name. When null, the screen shows a default name (such as "Step 1")                                                                                                                                                |
| `description`                     | `string \| null`  | Description                                                                                                                                                                                                             |
| `enabled`                         | `boolean \| null` | Whether it is enabled                                                                                                                                                                                                   |
| `defaultZone`                     | `string \| null`  | One of "ai" (run by an Agent), "gate" (review step), "automation" (external automation) and "branch" (branch)                                                                                                           |
| `automationConfig`                | `object \| null`  | Settings of the external automation (only for a step whose defaultZone is "automation"; null if it has no settings). In the preview of a shared project, only the name of the destination (destinationName) is returned |
| `automationConfig.destinationId`  | `string`          | ID of the destination (UUID). destinationId from the list of destinations (GET /v1/projects/automation-destinations)                                                                                                    |
| `automationConfig.body`           | `object`          | Shape of the body sent to the destination (a JSON object). Values can be inserted into strings with {{name}} (see the rules below)                                                                                      |
| `automationConfig.timeoutSeconds` | `number`          | How long to wait for the response of the destination (seconds, 1 to 300)                                                                                                                                                |
| `branchConfig`                    | `object \| null`  | Settings of the branch (only for a step whose defaultZone is "branch"; null for other steps and for a branch step not yet set up). Also returned in the preview of a published project                                  |
| `branchConfig.lanes[]`            | `object[]`        | Lanes: id, name (null for a lane without a name; optional when updating) and stepIds (the IDs of the steps in the lane, run from top to bottom)                                                                         |
| `branchConfig.rules[]`            | `object[]`        | Conditions: id, kind (what to check and the kind of rule), the values for that kind, and to (where to go when it matches)                                                                                               |
| `branchConfig.otherwise`          | `object`          | Where to go when no condition matches                                                                                                                                                                                   |
| `reworkToStepId`                  | `string \| null`  | ID of the step to go back to when work is sent back (used by review steps)                                                                                                                                              |
| `gateConfig`                      | `object \| null`  | Settings of a review step (the table below)                                                                                                                                                                             |
| `gateKind`                        | `string \| null`  | Kind of review: "review" (a person decides on the Agent's result) or "manual" (a person does the work and then proceeds)                                                                                                |
| `schedule`                        | `object \| null`  | Time of the step (workflow only): expression (cron expression) and timezone                                                                                                                                             |
| `scheduleNextFireAt`              | `string \| null`  | When the step is next scheduled to run by its time (ISO 8601)                                                                                                                                                           |
| `onDenied`                        | `string \| null`  | What happens "when it cannot run under the rules": "gate" (request a review), "closed\_failed" (close as failed), or "goto" (proceed to the step in outcomeRoutes)                                                      |
| `onDegraded`                      | `string \| null`  | What happens "when the Agent reports a failure": "gate" (request a review), "proceed" (proceed as is), or "goto" (proceed to the step in outcomeRoutes)                                                                 |
| `outcomeRoutes`                   | `object \| null`  | Where to proceed when onDenied or onDegraded is "goto"                                                                                                                                                                  |
| `outcomeRoutes.onDenied.stepId`   | `string`          | ID of the step to proceed to "when it cannot run under the rules"                                                                                                                                                       |
| `outcomeRoutes.onDegraded.stepId` | `string`          | ID of the step to proceed to "when the Agent reports a failure"                                                                                                                                                         |
| `laneId`                          | `string \| null`  | ID of the lane this step belongs to                                                                                                                                                                                     |
| `placementExecution`              | `string \| null`  | "parallel" (run the Agents placed in this step at the same time). null runs them one at a time in placement order                                                                                                       |
| `outputConfig`                    | `object \| null`  | Values and file roles passed to the next step (only for an "ai" step in a workflow; null when not set). Also returned in the preview of a published project                                                             |
| `outputConfig.values[]`           | `object[]`        | Values for the next step: name and description (the description can be omitted)                                                                                                                                         |
| `outputConfig.files[]`            | `object[]`        | File roles to attach to output files: role (the name of the role) and description (can be omitted)                                                                                                                      |
| `digest`                          | `string`          | The value to send as baseDigest when editing the step                                                                                                                                                                   |

Rules for `automationConfig`: it has only three keys, `destinationId` (required), `body` (`{}` if omitted) and `timeoutSeconds` (60 if omitted). null cannot be sent for `body` or `timeoutSeconds` (it is not the same as omitting them). `automationConfig` itself can be omitted. An external automation step without settings can be saved, but it needs settings before a workflow run starts. Sending null when you edit a step removes the settings. A wrong shape or value is `400` (`invalid_parameter`, with the name of the field such as `automationConfig.destinationId` in `error.param`). `body` can be up to 16 KiB and 16 levels deep, a rule separate from the limit of the whole request (32 KiB). The names you can insert into strings of `body` are only these ten: `previous.output` (the output of the previous step, up to 20,000 characters), `previous.summary` (its summary), `run.id`, `step.id`, `step.name`, `project.id`, `project.name`, `input.subject`, `input.body` (the subject and body of the input that started the run) and `idempotency_key` (a value that stays the same on retries). If the content does not meet these rules, it is `400` (`automation_body_invalid`).

Rules for `outputConfig`: up to 5 values (`values`) and up to 3 roles (`files`). `name` and `role` are up to 40 characters and `description` up to 200 characters; `description` can be omitted. Leading and trailing spaces and line breaks are removed when saved, and a line break or other control character in the middle is refused. When both values and roles are empty, it becomes null (not set). A value name and a role name cannot repeat within one step. The agent on this step is asked to return the named values (text, up to 1,000 characters each; anything beyond is cut off) and which output file has which role, and these are passed to the next step. A value that was not returned or a file that was not found is not guessed; the next step is told so. The values are not used for success or failure or for branch rules. Sending null with the API that updates a step removes it, and so does changing the step to a zone other than "ai". It cannot be set on a cycle step. When the rules are not met, it is 400 `output_config_invalid` (`error.param` is `outputConfig`).

Rules for `branchConfig`: add `branchConfig` with the API that updates a step, after adding the branch step (it cannot be sent with the API that adds a step). First, place the steps that make up the lanes right after the branch step, one lane after another. `lanes` holds 1 to 12 lanes (a project has up to 12 steps in all, including the branch step, so in practice up to 11), and every lane needs at least one step (a step cannot be in two lanes; `name` is up to 50 characters). `rules` are checked from the top, and the run goes to the `to` of the first matching condition (up to 8 conditions; with none, it always uses `otherwise`). `to` is `{"kind": "lane", "laneId": …}` or `{"kind": "merge"}` (join directly), and `otherwise` is either of those or `{"kind": "ask"}` (let a person choose); if omitted, it is `merge`. `lanes[].id` and `rules[].id` are up to 64 letters, digits, `_` and `-`, and cannot repeat within the same settings. `stepIds` are step IDs (UUIDs). A branch step cannot be placed inside a lane, and a branch step and its lanes are placed outside parallel lanes.

Rule kinds (`rules[].kind`):

| kind                 | Values                                                                                                                                                                       | Matches when                                                                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `text_contains`      | value (up to 200 characters; not whitespace only), negate                                                                                                                    | The result text of the previous step contains value (does not, when negate is true)                                                              |
| `json_field`         | path (a dot-separated field name; up to 200 characters), op ("eq", "ne", "gte", "lte", "exists"), value (except for "exists"; a string of up to 200 characters, or a number) | The field of the previous step's result JSON equals, differs from, is at least, or is at most value ("exists": the field is present)             |
| `files_exist`        | negate                                                                                                                                                                       | There are output files (there are none, when negate is true)                                                                                     |
| `files_count`        | op ("gte", "lte"), value (a whole number of 0 or more)                                                                                                                       | The number of output files is at least or at most value                                                                                          |
| `file_type`          | fileType ("pdf", "excel", "word", "powerpoint", "image")                                                                                                                     | There is an output file of that type                                                                                                             |
| `file_name_contains` | value (up to 200 characters; not whitespace only)                                                                                                                            | An output file name contains value                                                                                                               |
| `duration_minutes`   | op ("gte", "lte"), value (minutes; a whole number of 0 or more)                                                                                                              | The processing time of the previous step is at least or at most value minutes                                                                    |
| `send_backs`         | op ("gte"), value (a whole number of 0 or more)                                                                                                                              | The step was sent back at least value times                                                                                                      |
| `mutating`           | negate                                                                                                                                                                       | Write operations were made in the previous step (none were, when negate is true)                                                                 |
| `no_change_reported` | —                                                                                                                                                                            | The Agent reported that no changes were needed                                                                                                   |
| `ai`                 | question (a yes/no question; up to 200 characters; not whitespace only)                                                                                                      | A model that only judges reads the beginning of the previous step's output and answers yes (refused where it cannot be used in this environment) |

An example body for the API that updates a step (two lanes: go to "Invoices" if there is a PDF output file, join directly if the result text contains "out of scope", and otherwise go to "Others"):

```json
{
  "baseDigest": "<the step's digest>",
  "branchConfig": {
    "lanes": [
      { "id": "lane-invoice", "name": "Invoices", "stepIds": ["3f6c1d2e-8b4a-4c1e-9f0a-1b2c3d4e5f60"] },
      { "id": "lane-other", "name": "Others", "stepIds": ["7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"] }
    ],
    "rules": [
      { "id": "row-pdf", "kind": "file_type", "fileType": "pdf", "to": { "kind": "lane", "laneId": "lane-invoice" } },
      { "id": "row-skip", "kind": "text_contains", "value": "out of scope", "to": { "kind": "merge" } }
    ],
    "otherwise": { "kind": "lane", "laneId": "lane-other" }
  }
}
```

Settings of a review step (`gateConfig`):

| Field                   | Type             | Description                                                                                                                                                         |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approverUserIds`       | `array`          | Array of user IDs of the reviewers (up to 20 project members)                                                                                                       |
| `deadlineHours`         | `number \| null` | Review deadline (hours; 1 to 720)                                                                                                                                   |
| `mode`                  | `string \| null` | Review method: "blocking" (wait for the reviewer's decision) or "notify\_only" (proceed automatically after the deadline)                                           |
| `overdueAction`         | `string \| null` | After the deadline: "none" (notify and keep waiting), "proceed" (proceed automatically), "send\_back" (send back automatically), or "reject" (reject automatically) |
| `escalateToUserId`      | `string \| null` | User ID of the contact when the deadline passes (a project member)                                                                                                  |
| `destinations`          | `array`          | Steps the reviewer can choose to proceed to (2 to 5 steps after this step). Not included when not set                                                               |
| `destinations[].id`     | `string`         | Destination ID (up to 64 letters, digits, \_ and -)                                                                                                                 |
| `destinations[].label`  | `string`         | Name shown on the screen (up to 100 characters)                                                                                                                     |
| `destinations[].stepId` | `string`         | ID of the step to proceed to                                                                                                                                        |

When a review step has no settings (`gateConfig` is null, or a field is missing), it works with `mode` `"blocking"`, `deadlineHours` 24 hours, `overdueAction` `"none"`, and no contact after the deadline. Sending null for `deadlineHours`, `overdueAction`, or `escalateToUserId` works the same (sending null for `mode` returns `400 Bad Request` (`invalid_parameter`)). When `gateKind` is null, it is `"review"`.

Depending on the type of the project, some settings cannot be set on steps.

| Step setting                                                                       | workflow                      | cycle                                 |
| ---------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------- |
| Review steps ("gate" for defaultZone) and their settings (gateConfig and gateKind) | Can be set                    | 400 (cycle\_gate\_not\_allowed)       |
| External automation steps ("automation" for defaultZone)                           | Can be set                    | 400 (cycle\_automation\_not\_allowed) |
| Branch steps ("branch" for defaultZone) and branchConfig                           | Can be set                    | 400 (cycle\_branch\_not\_allowed)     |
| "gate" for onDenied and onDegraded                                                 | Can be set                    | 400 (cycle\_gate\_not\_allowed)       |
| "goto" for onDenied and onDegraded, and outcomeRoutes                              | Can be set                    | 400 (cycle\_route\_not\_allowed)      |
| "parallel" for placementExecution                                                  | Can be set on "ai" steps only | 400 (parallel\_workflow\_only)        |
| Values and file roles passed to the next step (outputConfig)                       | Can be set on "ai" steps only | 400 (output\_config\_invalid)         |
| schedule (time of the step)                                                        | Can be set                    | 400 (invalid\_parameter)              |
| reworkToStepId (step to send back to)                                              | Can be set                    | 400 (invalid\_parameter)              |

For a cycle, `schedule` and `reworkToStepId` are rejected only when a value other than null is sent (null is accepted so that a step you got can be sent back as is). For a cycle, how often an Agent runs is decided by the sweep of the placement, not by the step.

### POST`/v1/projects/{projectId}/steps`

Adds a step. Only owners can call this API.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

| Field                | Type             | Required | Description                                                                                                                                                                                                 |
| -------------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               | `string \| null` | —        | Step name (up to 100 characters; an empty string or null means the default name; cannot be only whitespace)                                                                                                 |
| `description`        | `string \| null` | —        | Description (up to 2000 characters; an empty string or null means no description)                                                                                                                           |
| `defaultZone`        | `string`         | —        | One of "ai", "gate", "automation" and "branch". "ai" if omitted. null or an empty string cannot be sent                                                                                                     |
| `automationConfig`   | `object \| null` | —        | Settings of the external automation (only for a step whose defaultZone is "automation"; see automationConfig in Step Fields and the rules below). If omitted, the step is added without settings            |
| `branchConfig`       | `—`              | —        | Cannot be sent (400 step\_reference\_on\_create). After adding the step, place the lane steps after it, then set it with the API that updates a step                                                        |
| `outputConfig`       | `object \| null` | —        | Values and file roles passed to the next step (only for a step whose defaultZone is "ai"; see outputConfig in Step Fields and the rules above). Can be omitted                                              |
| `afterStepId`        | `string`         | —        | Add the step after this step (the ID of a step of this project)                                                                                                                                             |
| `beforeStepId`       | `string`         | —        | Add the step before this step (the ID of a step of this project). If both afterStepId and beforeStepId are specified, the step is added before this step. If both are omitted, the step is added at the end |
| `gateConfig`         | `object \| null` | —        | Settings of a review step (same form as gateConfig in Step Fields; destinations are set when editing a step). null means no settings                                                                        |
| `placementExecution` | `string \| null` | —        | "parallel" runs Agents at the same time. null or "serial" runs them one at a time                                                                                                                           |

The added step is enabled. In a project with lanes, the step goes into the same lane as the step in beforeStepId when it is specified, or as the step in afterStepId otherwise.

#### Request Example

**Create step**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Difference report",
  "description": null,
  "defaultZone": "ai",
  "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': 'Difference report', 'description': None, 'defaultZone': 'ai', 'afterStepId': 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "Difference report", "description": null, "defaultZone": "ai", "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"name": "Difference report", "description": null, "defaultZone": "ai", "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (201 Created)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `step`               | `object`         | The added step                                                                                                                                                                                                                                                                                                                    |
| `steps`              | `array`          | All steps after the addition (in order)                                                                                                                                                                                                                                                                                           |
| `stepsDigest`        | `string`         | The value for the order of the steps after the addition                                                                                                                                                                                                                                                                           |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "step": {
    "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "position": 3,
    "name": "Difference report",
    "description": null,
    "enabled": true,
    "defaultZone": "ai",
    "automationConfig": null,
    "branchConfig": null,
    "reworkToStepId": null,
    "gateConfig": null,
    "gateKind": null,
    "schedule": null,
    "scheduleNextFireAt": null,
    "onDenied": null,
    "onDegraded": null,
    "outcomeRoutes": null,
    "laneId": null,
    "placementExecution": null,
    "outputConfig": null,
    "digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
  },
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "Amount check",
      "description": "Matches invoice amounts against line items",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "Difference check",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "Difference report",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
    }
  ],
  "stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                                  | Description                                                                                                                                                                                                                                                                                                       |
| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`                   | projectId is not a UUID, afterStepId or beforeStepId is not a step of this project, a field has the wrong type, length, or value (including a whitespace-only name, and null or an empty string for defaultZone), or approvers or escalateToRef was sent in gateConfig (use approverUserIds and escalateToUserId) |
| `400`  | `invalid_body`                        | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                   |
| `400`  | `step_reference_on_create`            | destinations was sent in gateConfig (including null or an empty array; set destinations with the API that edits a step, after adding the step), or branchConfig was sent (error.param is branchConfig; after adding the step, place the lane steps after it, then set it with the API that edits the step)        |
| `400`  | `cycle_gate_not_allowed`              | Tried to add a review step to a cycle                                                                                                                                                                                                                                                                             |
| `400`  | `cycle_branch_not_allowed`            | Tried to add a branch step ("branch") to a cycle                                                                                                                                                                                                                                                                  |
| `400`  | `branch_step_settings`                | A field that cannot be used in a branch step was sent. Do not send that field (its name is in error.param)                                                                                                                                                                                                        |
| `400`  | `output_config_invalid`               | outputConfig has a wrong shape, count or length, a control character in the middle of name, role or description, or a repeated name, or it was sent for a step that is not "ai" or for a cycle step (see the rules above). error.param is outputConfig                                                            |
| `400`  | `automation_body_invalid`             | The content of automationConfig.body does not meet the rules (16 KiB, depth 16, names you can insert). error.param is automationConfig.body                                                                                                                                                                       |
| `400`  | `automation_config_not_allowed`       | automationConfig was specified for a step whose defaultZone is not "automation"                                                                                                                                                                                                                                   |
| `400`  | `automation_step_settings`            | A field that cannot be used in an external automation step (review, time, destinations, running at the same time or the send-back target) was sent. Do not send that field (its name is in error.param)                                                                                                           |
| `400`  | `cycle_automation_not_allowed`        | An external automation step ("automation") was specified for a cycle                                                                                                                                                                                                                                              |
| `400`  | `automation_destination_missing`      | The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations, or disable the step. If no destinations are listed, ask an administrator                                                                |
| `400`  | `automation_destination_inactive`     | The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations, or disable the step                                                                |
| `409`  | `automation_dlp_enabled`              | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration                                                                                                                                                                                    |
| `409`  | `automation_destinations_unavailable` | Destinations for external automation are not available in this environment. Ask an administrator to set up destinations for external automation                                                                                                                                                                   |
| `400`  | `parallel_workflow_only`              | "parallel" was specified for a step of a cycle                                                                                                                                                                                                                                                                    |
| `400`  | `parallel_ai_only`                    | "parallel" was specified for a review step                                                                                                                                                                                                                                                                        |
| `400`  | `parallel_not_for_marketplace`        | "parallel" was specified in a project where a registered Agent of the Marketplace edition is placed                                                                                                                                                                                                               |
| `400`  | `approver_not_member`                 | A user who is not a member was specified as a reviewer                                                                                                                                                                                                                                                            |
| `400`  | `approvers_required`                  | Tried to add a review step without reviewers to an active workflow                                                                                                                                                                                                                                                |
| `400`  | `escalate_to_not_member`              | A user who is not a member was specified as the contact when the deadline passes                                                                                                                                                                                                                                  |
| `403`  | `insufficient_scope`                  | The project:write scope is missing                                                                                                                                                                                                                                                                                |
| `403`  | `forbidden`                           | Called with a system integration token                                                                                                                                                                                                                                                                            |
| `403`  | `owner_only`                          | A member who is not an owner                                                                                                                                                                                                                                                                                      |
| `403`  | `sso_required`                        | The user does not sign in with SSO                                                                                                                                                                                                                                                                                |
| `404`  | `project_not_found`                   | The project does not exist, or you are not a member                                                                                                                                                                                                                                                               |
| `409`  | `too_many_steps`                      | There are already 12 steps                                                                                                                                                                                                                                                                                        |
| `409`  | `flow_structure_conflict`             | Conflicts with the lane definition or with how branch steps are placed (for a branch step, the reason is in error.reason; see below the error table of the API that reorders steps)                                                                                                                               |
| `413`  | `body_too_large`                      | The body exceeds 32 KiB                                                                                                                                                                                                                                                                                           |
| `415`  | `unsupported_media_type`              | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                              |
| `409`  | `definition_invalid`                  | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                          |
| `503`  | `approval_setting_unavailable`        | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                          |
| `503`  | `definition_busy`                     | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                         |

### PATCH`/v1/projects/{projectId}/steps/{stepId}`

Edits a step. Only the fields you send are changed. Only owners can call this API.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `stepId`    | `string` | 必須 | Step ID (UUID)    |

#### Request Body

| Field                | Type             | Required | Description                                                                                                                                                                                                                                             |
| -------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`         | `string`         | Yes      | The digest of the step                                                                                                                                                                                                                                  |
| `name`               | `string \| null` | —        | Step name (up to 100 characters). An empty string or null resets it to the default name. Cannot be only whitespace                                                                                                                                      |
| `description`        | `string`         | —        | Description (up to 2000 characters; cannot be an empty string, only whitespace, or null)                                                                                                                                                                |
| `defaultZone`        | `string`         | —        | One of "ai", "gate", "automation" and "branch"                                                                                                                                                                                                          |
| `automationConfig`   | `object \| null` | —        | Settings of the external automation (only for a step whose defaultZone is "automation"; see automationConfig in Step Fields and the rules below). null removes the settings                                                                             |
| `branchConfig`       | `object \| null` | —        | Settings of the branch (only for a step whose defaultZone is "branch"; see branchConfig in Step Fields and the rules below). Sending it replaces the whole setting; null removes it                                                                     |
| `outputConfig`       | `object \| null` | —        | Values and file roles passed to the next step (only for a step whose defaultZone is "ai"; see outputConfig in Step Fields and the rules above). Sending it replaces the whole setting; null removes it                                                  |
| `enabled`            | `boolean`        | —        | Whether it is enabled. In a cycle, when it is disabled the placements on the step take no new starts (starts already accepted are not cancelled), and when it is enabled again the placements that had sweeping enabled go back to their saved schedule |
| `gateConfig`         | `object \| null` | —        | Settings of a review step. Only the fields you send are overlaid on the current values. null removes the settings                                                                                                                                       |
| `gateKind`           | `string \| null` | —        | "review" or "manual"                                                                                                                                                                                                                                    |
| `reworkToStepId`     | `string \| null` | —        | Step to send back to (a step before this step). null removes it                                                                                                                                                                                         |
| `onDenied`           | `string \| null` | —        | "gate", "closed\_failed", or "goto"                                                                                                                                                                                                                     |
| `onDegraded`         | `string \| null` | —        | "gate", "proceed", or "goto"                                                                                                                                                                                                                            |
| `outcomeRoutes`      | `object \| null` | —        | Where to proceed for "goto" (steps after this step). Sending it replaces the whole value (send onDegraded together even when changing only onDenied). null removes it. If it contains neither onDenied nor onDegraded, it is the same as not sending it |
| `placementExecution` | `string \| null` | —        | "parallel" runs Agents at the same time. null or "serial" runs them one at a time                                                                                                                                                                       |
| `schedule`           | `object \| null` | —        | Time of the step (workflow only): expression (a 5-field cron expression) and timezone (UTC if omitted). null removes it                                                                                                                                 |

Send at least one field besides baseDigest.

When you change the zone (`defaultZone`), the settings of the previous zone are removed (turning a step into an external automation step removes its review, time and similar settings; turning it into another zone removes `automationConfig`; turning it into a zone other than "ai" also removes `outputConfig`). A step that holds Agents cannot be turned into an external automation step.

Turning a step into a branch step removes its review, time, destination options, outcome handling, send-back target and run-at-the-same-time settings<!-- -->, and its external automation settings<!-- -->. A step that holds Agents cannot be turned into a branch step.

For the first step, the time of the step starts a workflow run at that time only when the project has no enabled time trigger. For other steps, the workflow run waits until that time.

Changing the reviewers (`approverUserIds`) or the review method (`mode`) is recorded in the records (audit trail).

#### Request Example

**Update step**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok",
  "name": "Amount check (tax included)"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok', 'name': 'Amount check (tax included)'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok", "name": "Amount check (tax included)"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok", "name": "Amount check (tax included)"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `step`               | `object`         | The step after the edit (with a new digest)                                                                                                                                                                                                                                                                                       |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "step": {
    "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "position": 1,
    "name": "Amount check (tax included)",
    "description": "Matches invoice amounts against line items",
    "enabled": true,
    "defaultZone": "ai",
    "automationConfig": null,
    "branchConfig": null,
    "reworkToStepId": null,
    "gateConfig": null,
    "gateKind": null,
    "schedule": null,
    "scheduleNextFireAt": null,
    "onDenied": null,
    "onDegraded": null,
    "outcomeRoutes": null,
    "laneId": null,
    "placementExecution": null,
    "outputConfig": null,
    "digest": "TqY6SuPTAr9He0NlMBKIRn7dBe_z651rRqQKNaluOgg"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`                   | projectId or stepId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name was set to only whitespace, description was set to an empty string, only whitespace, or null, null was sent for defaultZone or enabled, a field has the wrong type, length, or value, schedule or reworkToStepId was sent for a cycle, or approvers or escalateToRef was sent in gateConfig (use approverUserIds and escalateToUserId) |
| `400`  | `invalid_body`                        | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                                                                    |
| `400`  | `cycle_gate_not_allowed`              | Tried to make a step of a cycle a review step, or specified "gate" for onDenied or onDegraded                                                                                                                                                                                                                                                                                                                                                      |
| `400`  | `cycle_route_not_allowed`             | "goto" was specified for a step of a cycle                                                                                                                                                                                                                                                                                                                                                                                                         |
| `400`  | `cycle_branch_not_allowed`            | Tried to make a step of a cycle a branch step ("branch"), or sent branchConfig for a step of a cycle                                                                                                                                                                                                                                                                                                                                               |
| `400`  | `branch_step_settings`                | A field that cannot be used in a branch step was sent. Do not send that field (its name is in error.param)                                                                                                                                                                                                                                                                                                                                         |
| `400`  | `output_config_invalid`               | outputConfig has a wrong shape, count or length, a control character in the middle of name, role or description, or a repeated name, or it was sent for a step that is not "ai" or for a cycle step (see the rules above). error.param is outputConfig                                                                                                                                                                                             |
| `400`  | `invalid_branch_config`               | branchConfig has a wrong shape or value (1 to 12 lanes with at least one step each, up to 8 conditions, the id format, the rule values and so on; see the rules above). To remove it, send null                                                                                                                                                                                                                                                    |
| `400`  | `branch_config_not_allowed`           | branchConfig was sent for a step whose defaultZone is not "branch" (send null to remove it)                                                                                                                                                                                                                                                                                                                                                        |
| `400`  | `invalid_branch_lanes`                | The steps in branchConfig.lanes are not placed right after the branch step, lane by lane in the order of lanes (another step is between them). Reorder the steps first, then retry                                                                                                                                                                                                                                                                 |
| `400`  | `branch_nested`                       | Tried to use a lane step of another branch step for this branch step or its lanes. Remove it from the lanes of the other branch step first, or use a step outside them                                                                                                                                                                                                                                                                             |
| `400`  | `branch_in_lane`                      | The branch step or one of its lane steps is in a parallel lane. Move them out of the parallel lane, then retry                                                                                                                                                                                                                                                                                                                                     |
| `409`  | `branch_step_has_agents`              | Tried to make a step with placed Agents a branch step. Remove the placements first                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `branch_ai_unavailable`               | A rule of kind "ai" was sent, but branch steps that ask AI cannot be used in this environment. Ask an administrator to set up the AI decision, or use rules of other kinds                                                                                                                                                                                                                                                                         |
| `400`  | `automation_body_invalid`             | The content of automationConfig.body does not meet the rules (16 KiB, depth 16, names you can insert). error.param is automationConfig.body                                                                                                                                                                                                                                                                                                        |
| `400`  | `automation_config_not_allowed`       | automationConfig was specified for a step whose defaultZone is not "automation"                                                                                                                                                                                                                                                                                                                                                                    |
| `400`  | `automation_step_settings`            | A field that cannot be used in an external automation step (review, time, destinations, running at the same time or the send-back target) was sent. Do not send that field (its name is in error.param)                                                                                                                                                                                                                                            |
| `400`  | `cycle_automation_not_allowed`        | An external automation step ("automation") was specified for a cycle                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `automation_step_has_agents`          | Tried to turn a step that holds Agents into an external automation step. Remove the placements first                                                                                                                                                                                                                                                                                                                                               |
| `400`  | `automation_destination_missing`      | The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations, or disable the step. If no destinations are listed, ask an administrator                                                                                                                                                                                                 |
| `400`  | `automation_destination_inactive`     | The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations, or disable the step                                                                                                                                                                                                 |
| `409`  | `automation_dlp_enabled`              | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration                                                                                                                                                                                                                                                                                                                     |
| `409`  | `automation_destinations_unavailable` | Destinations for external automation are not available in this environment. Ask an administrator to set up destinations for external automation                                                                                                                                                                                                                                                                                                    |
| `400`  | `parallel_workflow_only`              | "parallel" was specified for a step of a cycle                                                                                                                                                                                                                                                                                                                                                                                                     |
| `400`  | `parallel_ai_only`                    | "parallel" was specified for a review step                                                                                                                                                                                                                                                                                                                                                                                                         |
| `400`  | `parallel_not_for_marketplace`        | "parallel" was specified in a project where a registered Agent of the Marketplace edition is placed                                                                                                                                                                                                                                                                                                                                                |
| `400`  | `approver_not_member`                 | A user who is not a member was specified as a reviewer                                                                                                                                                                                                                                                                                                                                                                                             |
| `400`  | `approvers_required`                  | In an active workflow, an enabled review step would have no reviewers                                                                                                                                                                                                                                                                                                                                                                              |
| `400`  | `escalate_to_not_member`              | A user who is not a member was specified as the contact when the deadline passes                                                                                                                                                                                                                                                                                                                                                                   |
| `400`  | `invalid_send_back_step`              | The step to send back to is not a step before this step                                                                                                                                                                                                                                                                                                                                                                                            |
| `400`  | `invalid_destinations`                | destinations has the wrong form (not 2 to 5 items, duplicate IDs, names, or steps, and so on)                                                                                                                                                                                                                                                                                                                                                      |
| `400`  | `destinations_gate_only`              | Tried to set destinations on a step that is not a review step                                                                                                                                                                                                                                                                                                                                                                                      |
| `400`  | `destinations_notify_only`            | Tried to set destinations on a step whose review method is "notify\_only"                                                                                                                                                                                                                                                                                                                                                                          |
| `400`  | `invalid_destination_step`            | A step in destinations is not a step after this step                                                                                                                                                                                                                                                                                                                                                                                               |
| `400`  | `invalid_outcome_routes`              | outcomeRoutes has the wrong form                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `400`  | `invalid_outcome_route`               | There is no destination for "goto", or it is not a step after this step                                                                                                                                                                                                                                                                                                                                                                            |
| `403`  | `insufficient_scope`                  | The project:write scope is missing                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `403`  | `forbidden`                           | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                             |
| `403`  | `owner_only`                          | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `sso_required`                        | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `403`  | `feature_not_permitted`               | Tried to change schedule from its saved value, but an administrator has not permitted scheduled run creation. Leaving schedule out, sending the same value or removing it with null is accepted                                                                                                                                                                                                                                                    |
| `404`  | `step_not_found`                      | The step does not exist, or you are not a member of the project                                                                                                                                                                                                                                                                                                                                                                                    |
| `409`  | `stale_base`                          | The step has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest                                                                                                                                                                                                                                                     |
| `409`  | `flow_structure_conflict`             | Conflicts with the lane definition or with how branch steps are placed (for a branch step, the reason is in error.reason; see below the error table of the API that reorders steps)                                                                                                                                                                                                                                                                |
| `413`  | `body_too_large`                      | The body exceeds 32 KiB                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `415`  | `unsupported_media_type`              | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `definition_invalid`                  | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                                                                                                                                                           |
| `503`  | `feature_permissions_unavailable`     | The feature permissions could not be checked. Retry after a while                                                                                                                                                                                                                                                                                                                                                                                  |
| `503`  | `approval_setting_unavailable`        | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                                                                                                                                                           |
| `503`  | `definition_busy`                     | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                                                                                                                                                          |

### PUT`/v1/projects/{projectId}/steps/order`

Reorders steps. Only owners can call this API.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

| Field        | Type     | Required | Description                                           |
| ------------ | -------- | -------- | ----------------------------------------------------- |
| `baseDigest` | `string` | Yes      | stepsDigest from Get Project                          |
| `stepIds`    | `array`  | Yes      | The IDs of all steps in the new order (no duplicates) |

#### Request Example

**Reorder steps**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
  "stepIds": [
    "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}'
```

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': '6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', '7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d', 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `steps`              | `array`          | All steps after reordering                                                                                                                                                                                                                                                                                                        |
| `stepsDigest`        | `string`         | The value for the order of the steps after reordering                                                                                                                                                                                                                                                                             |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "Amount check",
      "description": "Matches invoice amounts against line items",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 2,
      "name": "Difference report",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 3,
      "name": "Difference check",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
    }
  ],
  "stepsDigest": "TQbgPozTGXVTzA52FXfg_NPAcQRj94bGXmyUVP-WTeo",
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                                  |
| ------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`            | projectId is not a UUID, baseDigest is missing, empty, or not a string, or stepIds is not the order of all steps                                                                                             |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                              |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                                           |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                                       |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                                                 |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                           |
| `404`  | `project_not_found`            | The project does not exist, or you are not a member                                                                                                                                                          |
| `409`  | `stale_base`                   | The order of the steps has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest |
| `409`  | `flow_structure_conflict`      | Conflicts with the lane definition or with how branch steps are placed (for a branch step, the reason is in error.reason; see below the error table of the API that reorders steps)                          |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                                      |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                                         |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                     |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                     |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                                    |

When a `409` (`flow_structure_conflict`) comes from how branch steps are placed, `error.reason` holds the reason: `branch_nested` (a branch step would be in a lane of another branch step)<!-- -->, `branch_in_lane` (a branch step or its lane steps would be in a parallel lane), `fork_source_branch` (parallel lanes would split from a branch step or its lane steps), `join_next_branch_lane` (parallel lanes would join into a lane step of a branch step)<!-- -->, or `route_into_branch_lane` (a step outside a lane of a branch step would send back or route into that lane). The same applies to `flow_structure_conflict` from the APIs that add, update and delete a step.

### DELETE`/v1/projects/{projectId}/steps/{stepId}`

Deletes a step. Only owners can call this API. Send-back targets, destinations, and trigger start steps that point to the step are removed, and the placements and sweeps on the step are also removed. A step used by past workflow runs or review requests is kept for the records (`historyKept` is true). When the deletion becomes pending approval (`definitionApproval.status` is `"pending"`), the step is not deleted until it is approved, even though `deleted: true` is returned; it stays in the default read.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `stepId`    | `string` | 必須 | Step ID (UUID)    |

#### Request Example

**Delete step**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type              | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stepId`             | `string`          | ID of the deleted step                                                                                                                                                                                                                                                                                                            |
| `deleted`            | `boolean`         | Always true                                                                                                                                                                                                                                                                                                                       |
| `historyKept`        | `boolean \| null` | Whether the step was kept for the records. null when the deletion is pending approval (it is not deleted yet)                                                                                                                                                                                                                     |
| `steps`              | `array`           | All steps after the deletion                                                                                                                                                                                                                                                                                                      |
| `stepsDigest`        | `string`          | The value for the order of the steps after the deletion                                                                                                                                                                                                                                                                           |
| `definitionApproval` | `object \| null`  | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
  "deleted": true,
  "historyKept": false,
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "Amount check",
      "description": "Matches invoice amounts against line items",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "Difference check",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null,
      "digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
    }
  ],
  "stepsDigest": "OCkD5Kg3AClwepKwjLk5TZT1bwRFId09NV7SQKZOpL4",
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                                                                                                                                 |
| ------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or stepId is not a UUID                                                                                                                                                                                                                                                                           |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                                                                                                                                          |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                                                                                                                                      |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                                                                                                                                                |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                                                                                                                          |
| `404`  | `step_not_found`               | The step does not exist, or you are not a member of the project                                                                                                                                                                                                                                             |
| `409`  | `min_steps`                    | There are only as many steps as the minimum (2 for a workflow, 1 for a cycle)                                                                                                                                                                                                                               |
| `409`  | `flow_structure_conflict`      | Conflicts with the lane definition or with how branch steps are placed (to delete the step where lanes split, the step after a join, or the last step of a lane, fix the lane definition first; for a branch step, the reason is in error.reason; see below the error table of the API that reorders steps) |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                    |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                    |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                   |

## Placements

A placement is <!-- -->a library Agent<!-- --> placed in steps of a project. The same Agent can be placed only once in a project, and one placement can have multiple steps (its steps). For a cycle, how often an Agent runs (its sweep) is decided per pair of placement and step.<!-- --> Agents cannot be placed in external automation steps or branch steps.

### Endpoint List

| メソッド   | エンドポイント                                                         | 説明                                                           | Scope (SaaS)    |
| ------ | --------------------------------------------------------------- | ------------------------------------------------------------ | --------------- |
| GET    | `/v1/projects/{projectId}/placements`                           | List placements                                              | `project:read`  |
| GET    | `/v1/projects/{projectId}/placements/{placementId}`             | Get a placement                                              | `project:read`  |
| POST   | `/v1/projects/{projectId}/placements`                           | Place an Agent                                               | `project:write` |
| DELETE | `/v1/projects/{projectId}/placements/{placementId}`             | Remove a placement                                           | `project:write` |
| PUT    | `/v1/projects/{projectId}/placements/{placementId}/steps`       | Change the steps of a placement                              | `project:write` |
| GET    | `/v1/projects/{projectId}/memory-candidates`                    | Get the candidates for placement memory                      | `project:read`  |
| PATCH  | `/v1/projects/{projectId}/placements/{placementId}/memory`      | Change the memory of a placement                             | `project:write` |
| PATCH  | `/v1/projects/{projectId}/placements/{placementId}/instruction` | Change the instruction of a placement                        | `project:write` |
| PATCH  | `/v1/projects/{projectId}/placements/{placementId}/schedule`    | Stop, resume, or change the interval of a sweep (cycle only) | `project:write` |

### Placement Fields

The fields of a placement in `placements` of Get Project and in the responses of the placement APIs.

| Field                    | Type              | Description                                                                                                                                                                                                                                                                                                         |
| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placementId`            | `string`          | Placement ID (UUID)                                                                                                                                                                                                                                                                                                 |
| `agentId`                | `string \| null`  | ID of the placed Agent (the ID of the library Agent)                                                                                                                                                                                                                                                                |
| `displayOrder`           | `number \| null`  | Display order                                                                                                                                                                                                                                                                                                       |
| `name`                   | `string \| null`  | Agent name                                                                                                                                                                                                                                                                                                          |
| `description`            | `string \| null`  | Agent description                                                                                                                                                                                                                                                                                                   |
| `goal`                   | `string \| null`  | Agent goal (instructions)                                                                                                                                                                                                                                                                                           |
| `guardrail`              | `string \| null`  | Agent guardrail                                                                                                                                                                                                                                                                                                     |
| `skills`                 | `array`           | Skills used by the Agent (skillId and name)                                                                                                                                                                                                                                                                         |
| `skillCount`             | `number \| null`  | Number of skills                                                                                                                                                                                                                                                                                                    |
| `playbookId`             | `string \| null`  | ID of the playbook used by the Agent                                                                                                                                                                                                                                                                                |
| `playbookName`           | `string \| null`  | Playbook name                                                                                                                                                                                                                                                                                                       |
| `inputFiles`             | `array`           | Input files of the Agent (filename only)                                                                                                                                                                                                                                                                            |
| `stepIds`                | `array`           | Array of IDs of the steps of the placement                                                                                                                                                                                                                                                                          |
| `sweeps`                 | `array`           | Sweep settings (cycle): stepId, cron, timezone, and enabled for each step                                                                                                                                                                                                                                           |
| `runtimeConfigs`         | `array`           | Runtime settings per step (stepId and runtimeConfig). runtimeConfig is returned in the form saved. Project library bindings are returned in libraryBindings and are not included in runtimeConfig (runtimeConfig is null for a step that has only bindings)                                                         |
| `libraryBindings`        | `array`           | Which project library files are passed to each step, and under which name in the workspace (stepId, fileId, and workspaceName). An empty array when there are no bindings                                                                                                                                           |
| `memoryOrgId`            | `string \| null`  | Organization of the placement memory                                                                                                                                                                                                                                                                                |
| `memoryJobId`            | `string \| null`  | Job type of the placement memory                                                                                                                                                                                                                                                                                    |
| `instructionAddendum`    | `string \| null`  | An instruction for this project. When the placement runs, it is passed after the agent's goal (the agent itself is not changed). null when there is none                                                                                                                                                            |
| `agentOwnerUserId`       | `string \| null`  | User ID of the owner of the placed Agent                                                                                                                                                                                                                                                                            |
| `isShared`               | `boolean \| null` | Whether the placed Agent is shared                                                                                                                                                                                                                                                                                  |
| `runtimeKind`            | `string \| null`  | Kind of runtime of the Agent                                                                                                                                                                                                                                                                                        |
| `marketplaceAgentId`     | `string \| null`  | ID of the registered Agent in the Marketplace edition. null otherwise                                                                                                                                                                                                                                               |
| `exclusiveToThisProject` | `boolean \| null` | Whether this project is the only project where this Agent is placed                                                                                                                                                                                                                                                 |
| `agentStopped`           | `boolean \| null` | Whether an administrator has stopped the placed Agent. While it is stopped, the steps of this placement do not start and wait for it to be resumed                                                                                                                                                                  |
| `relink`                 | `object \| null`  | For a project imported from an exported definition, the playbooks and skills that the placed agent points to and that were not found. They are cleared when the agent is saved again. null if there are none                                                                                                        |
| `relink.playbook`        | `object \| null`  | The playbook that was not found (name and versionNo)                                                                                                                                                                                                                                                                |
| `relink.skills`          | `array`           | Array of the skills that were not found (name and versionNo)                                                                                                                                                                                                                                                        |
| `digest`                 | `string`          | The value to send as baseDigest to the APIs that change a placement (steps, memory, instruction, sweep, and library bindings). It is made from the steps, memory, instruction (only when set), runtime settings (including project library bindings), and sweeps, and does not change when the Agent itself changes |

### GET`/v1/projects/{projectId}/placements`

Gets all placements of a project.

#### Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                                                            |
| ------------ | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------- |
| `definition` | `string` | —  | With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition |

#### Request Example

**List placements**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type             | Description                                                                                                                                                                                          |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placements`     | `array`          | Array of placements. See "Placement Fields" for the fields of an item                                                                                                                                |
| `hasMore`        | `boolean`        | Always false                                                                                                                                                                                         |
| `definitionView` | `string \| null` | Only with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined |

#### Response Example

```json
{
  "placements": [
    {
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
      "displayOrder": 0,
      "name": "Accounting Agent",
      "description": "Matches invoice amounts against line items",
      "goal": "Match invoice amounts against line items and report differences",
      "guardrail": "Do not change amounts",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "Invoice reading"
        }
      ],
      "skillCount": 1,
      "playbookId": null,
      "playbookName": null,
      "inputFiles": [],
      "stepIds": [
        "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
      ],
      "sweeps": [],
      "runtimeConfigs": [
        {
          "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "runtimeConfig": null
        }
      ],
      "libraryBindings": [],
      "memoryOrgId": null,
      "memoryJobId": null,
      "instructionAddendum": null,
      "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "isShared": false,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "exclusiveToThisProject": true,
      "agentStopped": false,
      "relink": null,
      "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                     |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                                                                                                         |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                               |
| `403`  | `forbidden`          | Called with a system integration token                                                                                          |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                              |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                             |
| `409`  | `definition_invalid` | With definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason) |
| `503`  | `definition_busy`    | With definition=pending, another change to the same definition is in progress. Retry after a while                              |

### GET`/v1/projects/{projectId}/placements/{placementId}`

Gets one placement.

#### Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                                                            |
| ------------ | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------- |
| `definition` | `string` | —  | With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition |

#### Request Example

**Get placement**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type             | Description                                                                                                                                                                                          |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`      | `object`         | The placement. See "Placement Fields" for the fields                                                                                                                                                 |
| `definitionView` | `string \| null` | Only with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
  }
}
```

#### Error Responses

| Status | code                  | Description                                                                                                                     |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`   | projectId or placementId is not a UUID                                                                                          |
| `403`  | `insufficient_scope`  | The project:read scope is missing                                                                                               |
| `403`  | `forbidden`           | Called with a system integration token                                                                                          |
| `403`  | `sso_required`        | The user does not sign in with SSO                                                                                              |
| `404`  | `placement_not_found` | The placement does not exist, it belongs to another project, or you are not a member of the project                             |
| `409`  | `definition_invalid`  | With definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason) |
| `503`  | `definition_busy`     | With definition=pending, another change to the same definition is in progress. Retry after a while                              |

<!-- -->

### POST`/v1/projects/{projectId}/placements`

Places a library Agent in steps of a project. Only owners can call this API. Only your own Agents can be placed (copy a shared Agent in the library first, and then place the copy).

#### Request Body

| Field     | Type     | Required | Description                                                                                                                |
| --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `agentId` | `string` | Yes      | ID of the Agent to place (UUID)                                                                                            |
| `stepIds` | `array`  | —        | Array of IDs of the steps of the placement (up to 12 steps of this project). If omitted, the Agent is placed without steps |

- If the same Agent is already placed, `409 Conflict` (`placement_already_exists`) is returned. If the steps are also the same, the request is treated as a resend and the existing placement is returned. To change the steps, use the API that changes the steps of a placement.
- <!-- -->
  The input files attached to the Agent are passed as they are when it runs (they are not dropped even if they are not the project owner's files).
  <!-- -->
- A newly placed placement goes to the end of the placement order (`displayOrder`). However, placing the same Agent as a placement removed earlier (a placement kept because past workflow runs used it) brings that placement back with its original ID and position. When the placements of a step run one at a time, they run in this order. There is no API to reorder placements.

#### Request Example

**Place agent**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
  "stepIds": [
    "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
  headers={"Authorization": f"Bearer {token}"},
  json={'agentId': 'b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"]}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (201 Created)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placed placement. See "Placement Fields" for the fields                                                                                                                                                                                                                                                                       |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                              |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or agentId is not a UUID, or stepIds is invalid (more than 12, not steps of this project, the same step twice, and so on)                                                      |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                          |
| `400`  | `agent_not_found`              | The Agent in agentId does not exist or is not visible                                                                                                                                    |
| `400`  | `agent_not_owned`              | It is not your own Agent                                                                                                                                                                 |
| `400`  | `automation_step_no_agent`     | An Agent cannot be placed in an external automation step. Remove that step from stepIds                                                                                                  |
| `400`  | `branch_step_no_agent`         | An Agent cannot be placed in a branch step. Remove that step from stepIds                                                                                                                |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                       |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                   |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                             |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                       |
| `404`  | `project_not_found`            | The project does not exist, or you are not a member                                                                                                                                      |
| `409`  | `placement_already_exists`     | The same Agent is already placed (with different steps)                                                                                                                                  |
| `409`  | `unsupported_runtime`          | An Agent that cannot be placed with this API (such as a registered Agent of the Marketplace edition)                                                                                     |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                  |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                     |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                 |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                |

### DELETE`/v1/projects/{projectId}/placements/{placementId}`

Removes a placement. Only owners can call this API. A placement used by past workflow runs is kept for the records (`historyKept` is true). When the removal becomes pending approval (`definitionApproval.status` is `"pending"`), the placement is not removed until it is approved, even though `deleted: true` is returned; it stays in the default read. Past executions of a removed placement remain in the execution history with the original placement ID (`placementId`).

#### Request Example

**Remove placement**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type              | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placementId`        | `string`          | ID of the removed placement                                                                                                                                                                                                                                                                                                       |
| `deleted`            | `boolean`         | Always true                                                                                                                                                                                                                                                                                                                       |
| `historyKept`        | `boolean \| null` | Whether the placement was kept for the records. null when the removal is pending approval (it is not removed yet)                                                                                                                                                                                                                 |
| `definitionApproval` | `object \| null`  | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "deleted": true,
  "historyKept": false,
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                              |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or placementId is not a UUID                                                                                                                                                   |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                       |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                   |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                             |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                       |
| `404`  | `placement_not_found`          | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                      |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                 |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                |

### PUT`/v1/projects/{projectId}/placements/{placementId}/steps`

Replaces the steps of a placement with the steps you send. Only owners can call this API. The sweeps of the removed steps stop. An empty array can also be sent (the placement stays in the project, but it does not run because it has no steps).

#### Request Body

| Field        | Type     | Required | Description                                                                 |
| ------------ | -------- | -------- | --------------------------------------------------------------------------- |
| `baseDigest` | `string` | Yes      | The digest of the placement                                                 |
| `stepIds`    | `array`  | Yes      | Array of IDs of the steps of the placement (up to 12 steps of this project) |

#### Request Example

**Update placement steps**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "stepIds": [
    "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
  ]
}'
```

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'stepIds': ['5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', '7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d']},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepIds": ["5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"]}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placement after the change (with a new digest)                                                                                                                                                                                                                                                                                |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      },
      {
        "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "T4llTd4mnzoQvxn2wLcaiiTARKxh9AMsregqNUhNaCg"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                         |
| ------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or placementId is not a UUID, baseDigest is missing, empty, or not a string, or stepIds is invalid (more than 12, not steps of this project, the same step twice, and so on)              |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                     |
| `400`  | `automation_step_no_agent`     | An Agent cannot be placed in an external automation step. Remove that step from stepIds                                                                                                             |
| `400`  | `branch_step_no_agent`         | An Agent cannot be placed in a branch step. Remove that step from stepIds                                                                                                                           |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                                  |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                              |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                                        |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                  |
| `404`  | `placement_not_found`          | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                                 |
| `409`  | `stale_base`                   | The placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                             |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                                |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result            |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                            |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                           |

### GET`/v1/projects/{projectId}/memory-candidates`

Gets the organizations and job types that can be chosen for placement memory. The candidates are the organizations and job types of the project members.

#### Request Example

**Get memory candidates**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/memory-candidates \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/memory-candidates",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/memory-candidates",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/memory-candidates", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field           | Type             | Description                                                              |
| --------------- | ---------------- | ------------------------------------------------------------------------ |
| `organizations` | `array`          | Organization candidates (orgId and label)                                |
| `jobs`          | `array`          | Job type candidates (jobId and label)                                    |
| `unresolved`    | `number \| null` | Number of members whose organization and job type could not be confirmed |
| `hasMore`       | `boolean`        | Always false (all items are returned)                                    |

#### Response Example

```json
{
  "organizations": [
    {
      "orgId": "eng",
      "label": "Engineering"
    }
  ],
  "jobs": [
    {
      "jobId": "dev",
      "label": "Developer"
    }
  ],
  "unresolved": 0,
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                         |
| ------ | -------------------- | --------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                             |
| `403`  | `insufficient_scope` | The project:read scope is missing                   |
| `403`  | `forbidden`          | Called with a system integration token              |
| `403`  | `sso_required`       | The user does not sign in with SSO                  |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member |

### PATCH`/v1/projects/{projectId}/placements/{placementId}/memory`

Changes the memory of a placement (the organization and job type memory the Agent reads for the work). Only the fields you send are changed. Only owners can call this API.

#### Request Body

| Field        | Type             | Required | Description                                                                                        |
| ------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `baseDigest` | `string`         | Yes      | The digest of the placement                                                                        |
| `orgId`      | `string \| null` | —        | Organization. A new value must be one of the memory candidates. null or an empty string removes it |
| `jobId`      | `string \| null` | —        | Job type. A new value must be one of the memory candidates. null or an empty string removes it     |

Send at least one of orgId and jobId.

#### Request Example

**Update placement memory**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "orgId": "eng",
  "jobId": "dev"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'orgId': 'eng', 'jobId': 'dev'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "orgId": "eng", "jobId": "dev"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "orgId": "eng", "jobId": "dev"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/memory", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placement after the change (with a new digest)                                                                                                                                                                                                                                                                                |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": "eng",
    "memoryJobId": "dev",
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "Zhik2lSjR0HXwcqoh7OgPRUebWu1jON1_cveQsUv9r0"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                            | Description                                                                                                                                                                                         |
| ------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`             | projectId or placementId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, or orgId or jobId is neither a string nor null                                          |
| `400`  | `invalid_body`                  | The body is malformed JSON or not a JSON object                                                                                                                                                     |
| `400`  | `memory_not_candidate`          | A value that is not a memory candidate was specified                                                                                                                                                |
| `403`  | `insufficient_scope`            | The project:write scope is missing                                                                                                                                                                  |
| `403`  | `forbidden`                     | Called with a system integration token                                                                                                                                                              |
| `403`  | `owner_only`                    | A member who is not an owner                                                                                                                                                                        |
| `403`  | `sso_required`                  | The user does not sign in with SSO                                                                                                                                                                  |
| `404`  | `placement_not_found`           | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                                 |
| `409`  | `stale_base`                    | The placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest |
| `413`  | `body_too_large`                | The body exceeds 16 KiB                                                                                                                                                                             |
| `415`  | `unsupported_media_type`        | The Content-Type of the body is not application/json                                                                                                                                                |
| `409`  | `definition_invalid`            | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result            |
| `503`  | `approval_setting_unavailable`  | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                            |
| `503`  | `definition_busy`               | Another change to the same definition is in progress. Retry after a while                                                                                                                           |
| `503`  | `memory_candidates_unavailable` | The organizations and job types of the members cannot be confirmed (resend the request later)                                                                                                       |

### PATCH`/v1/projects/{projectId}/placements/{placementId}/instruction`

Changes the placement's instruction for this project (`instructionAddendum`). When the placement runs, it is passed after the agent's goal (the agent itself is not changed). Only owners of the project can call this API. It applies to runs started after the change and to sweeps not yet started (a run already started keeps the instruction it started with).

#### Request Body

| Field                 | Type             | Required | Description                                                                                               |
| --------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `baseDigest`          | `string`         | Yes      | The digest of the placement                                                                               |
| `instructionAddendum` | `string \| null` | Yes      | The instruction. Up to 5,000 characters. null, an empty string, or a string of only whitespace removes it |

#### Request Example

**Update placement instruction**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "instructionAddendum": "Match amounts including tax"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'instructionAddendum': 'Match amounts including tax'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "instructionAddendum": "Match amounts including tax"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "instructionAddendum": "Match amounts including tax"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/instruction", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placement after the change (with a new digest)                                                                                                                                                                                                                                                                                |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": "Match amounts including tax",
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "NyMPb1_BWzswz3SjOiLwDq_O2BZ0Qj72l3f3PqgYdiI"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                         |
| ------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or placementId is not a UUID, baseDigest is missing, empty, or not a string, or instructionAddendum is missing, is neither a string nor null, or exceeds 5,000 characters                 |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                     |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                                  |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                              |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                                        |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                  |
| `404`  | `placement_not_found`          | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                                 |
| `409`  | `stale_base`                   | The placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                             |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                                |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result            |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                            |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                           |

### PATCH`/v1/projects/{projectId}/placements/{placementId}/schedule`

For a cycle project, stops, resumes, or changes the interval of the sweep of a placement. Only the fields you send are changed. Only owners can call this API.

#### Request Body

| Field        | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest` | `string`  | Yes      | The digest of the placement                                                                                                                                                                                                                                                                                                                     |
| `stepId`     | `string`  | —        | ID of the step of the sweep (a step of the placement). Can be omitted for a placement with one step                                                                                                                                                                                                                                             |
| `enabled`    | `boolean` | —        | true sweeps and false stops. Even with true, it does not sweep while the step is disabled, the project is paused, an administrator has stopped the project or its Agent, or an administrator has suspended the person the project runs as (when the step is enabled again, or the project or Agent is resumed, it sweeps on the saved schedule) |
| `cron`       | `string`  | —        | Interval (a 5-field cron expression; up to 100 characters)                                                                                                                                                                                                                                                                                      |
| `timezone`   | `string`  | —        | Time zone (an IANA time zone name, up to 64 characters; for example, "Asia/Tokyo")                                                                                                                                                                                                                                                              |

- Send at least one of enabled, cron, and timezone. Fields you do not send keep their current values.
- When the step has no sweep yet (setting it for the first time), `cron` is required. If `enabled` is omitted, the sweep stays stopped, and if `timezone` is omitted, UTC is used.

#### Request Example

**Update placement schedule**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "enabled": true,
  "cron": "0 9 * * 1",
  "timezone": "Asia/Tokyo"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'stepId': '5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', 'enabled': True, 'cron': '0 9 * * 1', 'timezone': 'Asia/Tokyo'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "enabled": true, "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "enabled": true, "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placement after the change (with a new digest)                                                                                                                                                                                                                                                                                |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "cron": "0 9 * * 1",
        "timezone": "Asia/Tokyo",
        "enabled": true
      }
    ],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "TQwslacxj54G-mnF8xImeTexwswd53sGTRNesIiHwyU"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId, placementId, or stepId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, enabled, cron, or timezone has the wrong type, cron is not a valid cron expression or exceeds 100 characters, timezone is only whitespace, is not a valid time zone, or exceeds 64 characters, the project is a workflow, stepId is required but missing, or cron is missing when setting the sweep for the first time |
| `400`  | `invalid_body`                    | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                                                             |
| `400`  | `step_not_found`                  | stepId is not a step of this placement                                                                                                                                                                                                                                                                                                                                                                                                      |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                                                                                                                                                                                                                                                                                                                                          |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                      |
| `403`  | `owner_only`                      | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                                                                |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                                                          |
| `403`  | `feature_not_permitted`           | The change leaves the sweep enabled while turning it on or changing the cron or timezone of an enabled sweep (fields you leave out keep their current values), but an administrator has not permitted scheduled run creation. Sending enabled false is accepted                                                                                                                                                                             |
| `404`  | `placement_not_found`             | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                                                                                                                                                                                                                                                                         |
| `409`  | `stale_base`                      | The placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest                                                                                                                                                                                                                                         |
| `409`  | `principal`                       | The principal that runs the project (the current owner of the project) cannot be confirmed                                                                                                                                                                                                                                                                                                                                                  |
| `413`  | `body_too_large`                  | The body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `415`  | `unsupported_media_type`          | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `definition_invalid`              | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                                                                                                                                                    |
| `503`  | `feature_permissions_unavailable` | The feature permissions could not be checked. Retry after a while                                                                                                                                                                                                                                                                                                                                                                           |
| `503`  | `approval_setting_unavailable`    | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                                                                                                                                                    |
| `503`  | `definition_busy`                 | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                                                                                                                                                   |

## Triggers

A trigger is what sets a project in motion. A time trigger (`"cron"`) exists only in workflow projects and starts a workflow run at the times you set (a cycle runs at set times through each placement's patrol). A webhook trigger (`"webhook"`) exists only in cycle projects; firing it runs the placement tied to the trigger once, as an extra run. Trigger IDs and their current settings can be read from `triggers` of Get Project.<!-- --> The email start is not handled by this API (create, change, and delete it on the screen).

### Endpoint List

| メソッド   | エンドポイント                                              | 説明                                         | Scope (SaaS)    |
| ------ | ---------------------------------------------------- | ------------------------------------------ | --------------- |
| POST   | `/v1/projects/{projectId}/triggers`                  | Create a trigger                           | `project:write` |
| PATCH  | `/v1/projects/{projectId}/triggers/{triggerId}`      | Change a trigger                           | `project:write` |
| DELETE | `/v1/projects/{projectId}/triggers/{triggerId}`      | Delete a trigger                           | `project:write` |
| POST   | `/v1/projects/{projectId}/triggers/{triggerId}/fire` | Fire a trigger to run once as an extra run | `project:run`   |

### POST`/v1/projects/{projectId}/triggers`

Creates a trigger. Only owners can call it. It cannot be called with a system integration token.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

| Field         | Type             | Required          | Description                                                                                                                          |
| ------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | `string`         | Yes               | "cron" (time, workflow only) or "webhook" (cycle only)                                                                               |
| `name`        | `string \| null` | —                 | Name (up to 100 characters). Omit it or send null for no name                                                                        |
| `enabled`     | `boolean`        | —                 | Whether it is enabled. true if omitted. null cannot be sent                                                                          |
| `cron`        | `string`         | Yes for "cron"    | A 5-field cron expression (minute hour day month weekday, e.g. "0 9 \* \* 1"). Up to 100 characters                                  |
| `timezone`    | `string \| null` | —                 | Time zone of "cron" (an IANA name such as "Asia/Tokyo", up to 64 characters). UTC if omitted or null. An empty string cannot be sent |
| `startStepId` | `string \| null` | —                 | Step that "cron" starts from (the ID of a step of this project). From the first step if omitted or null                              |
| `placementId` | `string`         | Yes for "webhook" | ID of the placement that a fire runs                                                                                                 |
| `stepId`      | `string`         | Yes for "webhook" | ID of the step that a fire runs (a step of that placement)                                                                           |

Each type takes its own fields: `"cron"` takes `name`, `enabled`, `cron`, `timezone`, and `startStepId`; `"webhook"` takes `name`, `enabled`, `placementId`, and `stepId`. Sending a field of the other type returns `400 Bad Request` (`invalid_parameter`, with that field in `param`).

#### Response (201 Created)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger`            | `object`         | The created trigger, with the same fields as triggers\[] of Get Project (including digest; startFailure of a new "cron" trigger is null)                                                                                                                                                                                          |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Request Example

**Create triggers**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "type": "cron",
  "name": "Every Monday at 9:00",
  "cron": "0 9 * * 1",
  "timezone": "Asia/Tokyo"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers",
  headers={"Authorization": f"Bearer {token}"},
  json={'type': 'cron', 'name': 'Every Monday at 9:00', 'cron': '0 9 * * 1', 'timezone': 'Asia/Tokyo'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"type": "cron", "name": "Every Monday at 9:00", "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"type": "cron", "name": "Every Monday at 9:00", "cron": "0 9 * * 1", "timezone": "Asia/Tokyo"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "trigger": {
    "triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
    "type": "cron",
    "name": "Mondays at 9",
    "enabled": true,
    "lastFiredAt": null,
    "nextFireAt": "2026-11-16T00:00:00.000Z",
    "createdAt": "2026-11-10T09:00:00.000Z",
    "cron": "0 9 * * 1",
    "timezone": "Asia/Tokyo",
    "startStepId": null,
    "startFailure": null,
    "digest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId is not a UUID; type is missing, null, or not "cron" or "webhook"; cron is missing for "cron"; placementId or stepId is missing for "webhook"; a field of the other type was sent; cron cannot be read or exceeds 100 characters; timezone is not an IANA name, is an empty string, or exceeds 64 characters; name exceeds 100 characters; startStepId, placementId, or stepId is not a UUID; enabled is not a boolean; startStepId is not a step of this project; or stepId is not a step of that placement |
| `400`  | `invalid_body`                    | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `400`  | `webhook_cycle_only`              | Tried to create a "webhook" trigger in a project that is not a cycle (use "cron" for a workflow)                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `400`  | `cron_workflow_only`              | Tried to create a "cron" trigger in a cycle project (a cycle runs at set times through each placement's patrol)                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `403`  | `owner_only`                      | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `403`  | `feature_not_permitted`           | An administrator has not permitted scheduled run creation (checked whenever a trigger is created, whatever its type or enabled)                                                                                                                                                                                                                                                                                                                                                                                       |
| `404`  | `project_not_found`               | The project does not exist, or you are not a member                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `413`  | `body_too_large`                  | The body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `415`  | `unsupported_media_type`          | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `409`  | `definition_invalid`              | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                                                                                                                                                                                                                              |
| `503`  | `feature_permissions_unavailable` | The feature permissions could not be checked. Retry after a while                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `503`  | `approval_setting_unavailable`    | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `503`  | `definition_busy`                 | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### PATCH`/v1/projects/{projectId}/triggers/{triggerId}`

Changes a trigger. Only the fields you send are changed. Only owners can call it. It cannot be called with a system integration token.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                                                      |
| ----------- | -------- | -- | ------------------------------------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)                                       |
| `triggerId` | `string` | 必須 | Trigger ID (UUID; triggers\[].triggerId of Get Project) |

#### Request Body

| Field         | Type      | Required | Description                                                                |
| ------------- | --------- | -------- | -------------------------------------------------------------------------- |
| `baseDigest`  | `string`  | Yes      | The digest of the trigger (triggers\[].digest of Get Project)              |
| `name`        | `string`  | —        | Name (up to 100 characters)                                                |
| `enabled`     | `boolean` | —        | Whether it is enabled                                                      |
| `cron`        | `string`  | —        | A 5-field cron expression ("cron" only). Up to 100 characters              |
| `timezone`    | `string`  | —        | Time zone ("cron" only; an IANA name, up to 64 characters)                 |
| `startStepId` | `string`  | —        | Step to start from ("cron" only; the ID of a step of this project)         |
| `placementId` | `string`  | —        | ID of the placement that a fire runs ("webhook" only)                      |
| `stepId`      | `string`  | —        | ID of the step that a fire runs ("webhook" only; a step of that placement) |

- Send at least one field besides baseDigest.
- `type` cannot be changed (sending it returns `400 Bad Request`). To change the type, delete the trigger and create another.
- Fields cannot be cleared. Sending null, an empty string, or only whitespace returns `400 Bad Request`.

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger`            | `object`         | The trigger after the change (with a new digest), with the same fields as triggers\[] of Get Project                                                                                                                                                                                                                              |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Request Example

**Update 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA",
  "enabled": false
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA', 'enabled': False},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA", "enabled": false}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA", "enabled": false}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "trigger": {
    "triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
    "type": "cron",
    "name": "Mondays at 9",
    "enabled": false,
    "lastFiredAt": null,
    "nextFireAt": null,
    "createdAt": "2026-11-10T09:00:00.000Z",
    "cron": "0 9 * * 1",
    "timezone": "Asia/Tokyo",
    "startStepId": null,
    "startFailure": null,
    "digest": "hpCcTMyiZEFKOV5AE5g-Hszqkdf2P2HKL7AJz_s0RsU"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId or triggerId is not a UUID; baseDigest is missing, empty, or not a string; type was sent; no field to change was sent; null, an empty string, or only whitespace was sent for a field; a field not of the trigger's type was sent; a field has the wrong type, length, or value (as when creating); startStepId is not a step of this project; or stepId is not a step of that placement |
| `400`  | `invalid_body`                    | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                    |
| `400`  | `cron_workflow_only`              | Tried to change a "cron" trigger of a cycle project (it can be deleted)                                                                                                                                                                                                                                                                                                                            |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                                                                                                                                                                                                                                                                                                 |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                             |
| `403`  | `owner_only`                      | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                 |
| `403`  | `feature_not_permitted`           | Tried to enable a disabled trigger (enabled set to true), but an administrator has not permitted scheduled run creation. Changes that do not enable it are accepted                                                                                                                                                                                                                                |
| `404`  | `trigger_not_found`               | The trigger does not exist, belongs to another project, or is an email start trigger, or you are not a member of the project                                                                                                                                                                                                                                                                       |
| `409`  | `stale_base`                      | The trigger has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest                                                                                                                                                                                                  |
| `413`  | `body_too_large`                  | The body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                            |
| `415`  | `unsupported_media_type`          | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `definition_invalid`              | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result                                                                                                                                                                                                           |
| `503`  | `feature_permissions_unavailable` | The feature permissions could not be checked. Retry after a while                                                                                                                                                                                                                                                                                                                                  |
| `503`  | `approval_setting_unavailable`    | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                                                                                                                                                                                                                           |
| `503`  | `definition_busy`                 | Another change to the same definition is in progress. Retry after a while                                                                                                                                                                                                                                                                                                                          |

### DELETE`/v1/projects/{projectId}/triggers/{triggerId}`

Deletes a trigger. Only owners can call it. It cannot be called with a system integration token. When the deletion becomes pending approval (`definitionApproval.status` is `"pending"`), the trigger is not deleted until it is approved, even though `deleted: true` is returned; it stays in the default read.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `triggerId` | `string` | 必須 | Trigger ID (UUID) |

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggerId`          | `string`         | ID of the deleted trigger                                                                                                                                                                                                                                                                                                         |
| `deleted`            | `boolean`        | Always true                                                                                                                                                                                                                                                                                                                       |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Request Example

**Delete 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
  "deleted": true,
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                              |
| ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId or triggerId is not a UUID                                                                                                                                                     |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                       |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                   |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                             |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                       |
| `404`  | `trigger_not_found`            | The trigger does not exist, belongs to another project, or is an email start trigger, or you are not a member of the project                                                             |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                 |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                |

### POST`/v1/projects/{projectId}/triggers/{triggerId}/fire`

Fires a webhook trigger configured on a `cycle` project and runs the target agent **once, as an extra ad-hoc run**. Calling it for a `workflow` project returns `404 Not Found`.

The scheduled runs stay exactly as configured. A fired run is added separately from the schedule. Where an earlier fire has not started running yet, however, a later fire **may be merged** into that run. Where it is, `jobId` returns the same value as the earlier fire, so the number of fires and the number of runs do not necessarily match.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                               |
| ----------- | -------- | -- | -------------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)                |
| `triggerId` | `string` | 必須 | ID of the trigger to fire (UUID) |

#### Request Body

| パラメータ     | 型        | 必須 | 説明                                                                                                                                                                                |
| --------- | -------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventId` | `string` | 必須 | A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and \_ . : @ + - only                                     |
| `payload` | `any`    | —  | Arbitrary JSON passed to the agent. It is serialized to a JSON string and added to the request sent to the agent; anything beyond 8,000 characters after serialization is omitted |

#### Request Example

**Fire trigger**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "eventId": "order-20261118-0001",
  "payload": {
    "orderId": "A-1024"
  }
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
  headers={"Authorization": f"Bearer {token}"},
  json={'eventId': 'order-20261118-0001', 'payload': {'orderId': 'A-1024'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (202 Accepted)

| Field    | Type     | Description                                                                                              |
| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `result` | `string` | "accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)                       |
| `jobId`  | `string` | ID of the receiving job. It cannot be used to get run status (GET /v1/projects/{projectId}/runs/{runId}) |

#### Response Example

<!-- -->

<!-- -->

```json
{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
```

> **What 202 means here**
>
> This `202 Accepted` means only that **the request was recorded as accepted**. The run happens afterwards, and its outcome is not part of this response. Do not treat `202` as business success.

#### Resending

Idempotency is decided by the combination of project, trigger, and `eventId`. Resending the same content returns `202` with `result: "duplicate"`. Sending the same `eventId` with a different `payload` returns `409 Conflict` (`event_conflict`).

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                 |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_event_id`       | eventId is missing or has an invalid format                                                                                                                                                 |
| `400`  | `invalid_parameter`      | projectId or triggerId is not a UUID                                                                                                                                                        |
| `400`  | `invalid_body`           | The request body is malformed JSON or is not a JSON object                                                                                                                                  |
| `415`  | `unsupported_media_type` | A request body is sent with a Content-Type other than application/json                                                                                                                      |
| `403`  | `insufficient_scope`     | The project:run scope is missing                                                                                                                                                            |
| `404`  | `trigger_not_found`      | The project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified                                                         |
| `409`  | `trigger_disabled`       | The trigger is disabled                                                                                                                                                                     |
| `409`  | `project_not_active`     | The project is not in a runnable state                                                                                                                                                      |
| `409`  | `principal_suspended`    | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                       |
| `409`  | `admin_stopped`          | An administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it                                                                 |
| `409`  | `placement_unavailable`  | The target agent placement does not exist, no execution principal is configured, or the step of the placement is disabled (only a project owner can enable the step; enable it, then retry) |
| `409`  | `event_conflict`         | The same eventId was sent with a different payload                                                                                                                                          |
| `413`  | `body_too_large`         | The request body exceeds 16 KiB                                                                                                                                                             |

### Finding the Execution Started by a Fire

The execution history (`GET /v1/projects/{projectId}/executions`) cannot be filtered by the `jobId` in the response of a fire. Find it as follows.

1. Filter the execution history by the placement of the trigger (`placementId`) and the time of the fire (`from`).
2. Compare the `jobId` in the results of the candidate executions (`GET /v1/projects/{projectId}/executions/{executionId}`) with the `jobId` in the response of the fire.

Fires merged into an execution that has not started yet become one execution with the same `jobId`.

## Webhooks

A project webhook tells an https URL you choose when an event happens in the project. One webhook sends one event (`event`). A project can have up to 20. It is different from a webhook trigger (which is fired from outside to run the project).

- Only owners can call these 5 APIs (for the list and the deliveries too, a member who is not an owner gets `403 Forbidden` (`owner_only`)). They cannot be called with a system integration token.
- `secret` is write-only and is not returned in any response (`hasSecret` in the response tells whether one is set). Replacing its value does not change `digest`. Use a random string of letters and digits only for `secret`.

### Events

| event                  | Sent when                                |
| ---------------------- | ---------------------------------------- |
| `gate_reached`         | A review request arrives                 |
| `gate_due_soon`        | The deadline of a review request is near |
| `gate_overdue`         | A review request is past its deadline    |
| `run_deadline_overdue` | A workflow run is past its deadline      |
| `run_stalled`          | A workflow run stays stopped             |
| `run_closed`           | A workflow run ends                      |

### What Is Sent

The following JSON is sent with `POST`.

| Field         | Type             | Description                                                                                                             |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `event`       | `string`         | The event (a value in the table above)                                                                                  |
| `project_id`  | `string`         | Project ID                                                                                                              |
| `run_id`      | `string \| null` | ID of the workflow run                                                                                                  |
| `workitem_id` | `string \| null` | ID of the review request                                                                                                |
| `occurred_at` | `string`         | When the event happened (ISO 8601)                                                                                      |
| `link`        | `string \| null` | URL to open on the screen                                                                                               |
| `status`      | `string`         | Only for run\_closed. How the workflow run ended ("closed\_done", "closed\_failed", "closed\_rejected", or "cancelled") |

- Headers: `Content-Type: application/json` and `X-Agentic-Star-Event` (the event). When a `secret` is set, `X-Agentic-Star-Signature: sha256=<signature>` is also sent. The signature is the HMAC-SHA256 of the received body as is (its bytes) with `secret`, in hexadecimal. Compute the same on the receiving side and compare.
- Returning `2xx` within 10 seconds counts as delivered. On any other response (including redirects), a timeout, or a failed connection, it is sent again after 1, 5, and 30 minutes (up to 4 times including the first). The same event can arrive more than once.
- Delivery results are kept for 30 days and can be read with [List Deliveries](#list-webhook-deliveries).

### Endpoint List

| メソッド   | エンドポイント                                                    | 説明               | Scope (SaaS)    |
| ------ | ---------------------------------------------------------- | ---------------- | --------------- |
| GET    | `/v1/projects/{projectId}/webhooks`                        | List webhooks    | `project:read`  |
| POST   | `/v1/projects/{projectId}/webhooks`                        | Create a webhook | `project:write` |
| PATCH  | `/v1/projects/{projectId}/webhooks/{webhookId}`            | Change a webhook | `project:write` |
| DELETE | `/v1/projects/{projectId}/webhooks/{webhookId}`            | Delete a webhook | `project:write` |
| GET    | `/v1/projects/{projectId}/webhooks/{webhookId}/deliveries` | List deliveries  | `project:read`  |

### GET`/v1/projects/{projectId}/webhooks`

Gets all webhooks of the project (in the order they were created). Only owners can call it.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Response (200 OK)

| Field                     | Type              | Description                                                                                                                             |
| ------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `webhooks`                | `array`           | Array of webhooks                                                                                                                       |
| `webhooks[].webhookId`    | `string`          | Webhook ID                                                                                                                              |
| `webhooks[].event`        | `string \| null`  | Event it sends                                                                                                                          |
| `webhooks[].url`          | `string \| null`  | Destination URL                                                                                                                         |
| `webhooks[].enabled`      | `boolean \| null` | Whether it is enabled                                                                                                                   |
| `webhooks[].hasSecret`    | `boolean`         | Whether a secret is set (the secret is not returned)                                                                                    |
| `webhooks[].createdAt`    | `string \| null`  | Creation time (ISO 8601)                                                                                                                |
| `webhooks[].lastDelivery` | `object \| null`  | Result of the latest delivery (status, httpStatus, at). Deliveries waiting to be sent again are not included. null if there is none yet |
| `webhooks[].digest`       | `string`          | The value to send as baseDigest when changing the webhook                                                                               |
| `events`                  | `string[]`        | Events that can be sent                                                                                                                 |
| `hasMore`                 | `boolean`         | Always false (all webhooks are returned)                                                                                                |

#### Request Example

**Get webhooks**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "webhooks": [
    {
      "webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
      "event": "run_closed",
      "url": "https://example.com/hooks/agentic-star",
      "enabled": true,
      "hasSecret": true,
      "createdAt": "2026-11-10T09:00:00.000Z",
      "lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
      "digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
    }
  ],
  "events": ["gate_reached", "gate_due_soon", "gate_overdue", "run_deadline_overdue", "run_stalled", "run_closed"],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                         |
| ------ | -------------------- | --------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                             |
| `403`  | `insufficient_scope` | The project:read scope is missing                   |
| `403`  | `forbidden`          | Called with a system integration token              |
| `403`  | `owner_only`         | A member who is not an owner                        |
| `403`  | `sso_required`       | The user does not sign in with SSO                  |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member |

### POST`/v1/projects/{projectId}/webhooks`

Creates a webhook. Only owners can call it.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

| Field     | Type             | Required | Description                                                                                                                                                           |
| --------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event`   | `string`         | Yes      | Event to send (a value in "Events" above)                                                                                                                             |
| `url`     | `string`         | Yes      | Destination URL (up to 2048 characters). https only, without a user name or password. The host name must resolve to a public address that can be reached from outside |
| `secret`  | `string \| null` | —        | Value used for the signature (up to 256 characters). Omit it, or send null or an empty string, for no signature                                                       |
| `enabled` | `boolean`        | —        | Whether it is enabled. true if omitted                                                                                                                                |

#### Response (201 Created)

| Field     | Type     | Description                                                                                 |
| --------- | -------- | ------------------------------------------------------------------------------------------- |
| `webhook` | `object` | The created webhook, with the same fields as webhooks\[] of the list (lastDelivery is null) |

#### Request Example

**Create webhooks**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "event": "run_closed",
  "url": "https://example.com/hooks/agentic-star",
  "secret": "<secret>"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
  headers={"Authorization": f"Bearer {token}"},
  json={'event': 'run_closed', 'url': 'https://example.com/hooks/agentic-star', 'secret': '<secret>'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"event": "run_closed", "url": "https://example.com/hooks/agentic-star", "secret": "<secret>"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"event": "run_closed", "url": "https://example.com/hooks/agentic-star", "secret": "<secret>"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "webhook": {
    "webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
    "event": "run_closed",
    "url": "https://example.com/hooks/agentic-star",
    "enabled": true,
    "hasSecret": true,
    "createdAt": "2026-11-10T09:00:00.000Z",
    "lastDelivery": null,
    "digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
  }
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                                        |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId is not a UUID; event or url is missing or null; event is not one of the values above; url is not a string, is only whitespace, or exceeds 2048 characters; secret is not a string or exceeds 256 characters; or enabled is not a boolean |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                                    |
| `400`  | `invalid_url_format`     | url cannot be read as a URL                                                                                                                                                                                                                        |
| `400`  | `https_required`         | url is not https, or contains a user name or password                                                                                                                                                                                              |
| `400`  | `blocked_host`           | The host of url cannot receive webhooks (a local, private, or internal address)                                                                                                                                                                    |
| `400`  | `unresolvable_host`      | The host name of url could not be resolved                                                                                                                                                                                                         |
| `400`  | `too_many_webhooks`      | The project already has 20 webhooks                                                                                                                                                                                                                |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                                                                                                                                 |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                             |
| `403`  | `owner_only`             | A member who is not an owner                                                                                                                                                                                                                       |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                                 |
| `404`  | `project_not_found`      | The project does not exist, or you are not a member                                                                                                                                                                                                |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                                            |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                                               |

### PATCH`/v1/projects/{projectId}/webhooks/{webhookId}`

Changes a webhook. Only the fields you send are changed. Only owners can call it.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                                                   |
| ----------- | -------- | -- | ---------------------------------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)                                    |
| `webhookId` | `string` | 必須 | Webhook ID (UUID; webhooks\[].webhookId of the list) |

#### Request Body

| Field        | Type             | Required | Description                                                                                                               |
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest` | `string`         | Yes      | The digest of the webhook (webhooks\[].digest of the list)                                                                |
| `event`      | `string`         | —        | Event to send                                                                                                             |
| `url`        | `string`         | —        | Destination URL (the same rules as when creating)                                                                         |
| `secret`     | `string \| null` | —        | Value used for the signature (up to 256 characters). Replaced with the value you send. null or an empty string removes it |
| `enabled`    | `boolean`        | —        | Whether it is enabled                                                                                                     |

- Send at least one field besides baseDigest.
- `event`, `url`, and `enabled` cannot be cleared (sending null, an empty string, or only whitespace returns `400 Bad Request`).

#### Response (200 OK)

| Field     | Type     | Description                                                                                       |
| --------- | -------- | ------------------------------------------------------------------------------------------------- |
| `webhook` | `object` | The webhook after the change (with a new digest), with the same fields as webhooks\[] of the list |

#### Request Example

**Update c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8",
  "enabled": false
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8', 'enabled': False},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8", "enabled": false}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8", "enabled": false}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "webhook": {
    "webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
    "event": "run_closed",
    "url": "https://example.com/hooks/agentic-star",
    "enabled": false,
    "hasSecret": true,
    "createdAt": "2026-11-10T09:00:00.000Z",
    "lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
    "digest": "p6lFz_URDGJlbWylUwuz5Y41RzkRw7p7AFwUZOr6hpk"
  }
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                                                         |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or webhookId is not a UUID; baseDigest is missing, empty, or not a string; no field to change was sent; null, an empty string, or only whitespace was sent for event, url, or enabled; or a field has the wrong type, length, or value (as when creating) |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                     |
| `400`  | `invalid_url_format`     | url cannot be read as a URL                                                                                                                                                                                                                                         |
| `400`  | `https_required`         | url is not https, or contains a user name or password                                                                                                                                                                                                               |
| `400`  | `blocked_host`           | The host of url cannot receive webhooks (a local, private, or internal address)                                                                                                                                                                                     |
| `400`  | `unresolvable_host`      | The host name of url could not be resolved                                                                                                                                                                                                                          |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                                                                                                                                                  |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                                              |
| `403`  | `owner_only`             | A member who is not an owner                                                                                                                                                                                                                                        |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                                                  |
| `404`  | `webhook_not_found`      | The webhook does not exist or belongs to another project, or you are not a member of the project                                                                                                                                                                    |
| `409`  | `stale_base`             | The webhook has changed since you got it                                                                                                                                                                                                                            |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                                                             |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                                                                |

### DELETE`/v1/projects/{projectId}/webhooks/{webhookId}`

Deletes a webhook. Only owners can call it.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `webhookId` | `string` | 必須 | Webhook ID (UUID) |

#### Response (200 OK)

| Field       | Type      | Description               |
| ----------- | --------- | ------------------------- |
| `webhookId` | `string`  | ID of the deleted webhook |
| `deleted`   | `boolean` | Always true               |

#### Request Example

**Delete c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
  "deleted": true
}
```

#### Error Responses

| Status | code                 | Description                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or webhookId is not a UUID                                                             |
| `403`  | `insufficient_scope` | The project:write scope is missing                                                               |
| `403`  | `forbidden`          | Called with a system integration token                                                           |
| `403`  | `owner_only`         | A member who is not an owner                                                                     |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                               |
| `404`  | `webhook_not_found`  | The webhook does not exist or belongs to another project, or you are not a member of the project |

### GET`/v1/projects/{projectId}/webhooks/{webhookId}/deliveries`

Gets the delivery results of a webhook, newest first (the last 30 days). The body that was sent is not returned. Only owners can call it.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `webhookId` | `string` | 必須 | Webhook ID (UUID) |

#### Query Parameters

| Parameter | Type      | Default | Description                                          |
| --------- | --------- | ------- | ---------------------------------------------------- |
| `limit`   | `integer` | `50`    | Number of items to fetch (1-100). There is no cursor |

#### Response (200 OK)

| Field                        | Type             | Description                                                                                                |
| ---------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `deliveries`                 | `array`          | Array of delivery results (newest first)                                                                   |
| `deliveries[].deliveryId`    | `string \| null` | Delivery ID                                                                                                |
| `deliveries[].event`         | `string \| null` | Event                                                                                                      |
| `deliveries[].attempt`       | `number \| null` | Which attempt this is                                                                                      |
| `deliveries[].status`        | `string \| null` | "delivered" (arrived), "pending" (not sent yet, or waiting to be sent again), or "failed" (did not arrive) |
| `deliveries[].httpStatus`    | `number \| null` | HTTP status returned by the destination                                                                    |
| `deliveries[].at`            | `string \| null` | Time of the result (ISO 8601)                                                                              |
| `deliveries[].nextAttemptAt` | `string \| null` | When it is to be sent again (ISO 8601)                                                                     |
| `deliveries[].lastError`     | `string \| null` | Why it did not arrive (e.g. "http\_500", "timeout")                                                        |
| `hasMore`                    | `boolean`        | Whether there are older results than limit (when limit is 100, true when 100 items are returned)           |

#### Request Example

**Get deliveries**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "deliveries": [
    {
      "deliveryId": "1042",
      "event": "run_closed",
      "attempt": 1,
      "status": "delivered",
      "httpStatus": 200,
      "at": "2026-11-10T10:15:02.000Z",
      "nextAttemptAt": null,
      "lastError": null
    },
    {
      "deliveryId": "1031",
      "event": "run_closed",
      "attempt": 4,
      "status": "failed",
      "httpStatus": 503,
      "at": "2026-11-09T18:42:10.000Z",
      "nextAttemptAt": null,
      "lastError": "http_503"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or webhookId is not a UUID, or limit is not 1-100                                      |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                |
| `403`  | `forbidden`          | Called with a system integration token                                                           |
| `403`  | `owner_only`         | A member who is not an owner                                                                     |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                               |
| `404`  | `webhook_not_found`  | The webhook does not exist or belongs to another project, or you are not a member of the project |

## Workflow Runs

A workflow run is one pass through the steps of a workflow project in order. Cycle projects do not create workflow runs (read cycle executions in the execution history).

### Endpoint List

| メソッド  | エンドポイント                                           | 説明                                              | Scope (SaaS)    |
| ----- | ------------------------------------------------- | ----------------------------------------------- | --------------- |
| POST  | `/v1/projects/{projectId}/runs`                   | Start a workflow run                            | `project:run`   |
| GET   | `/v1/projects/{projectId}/runs/{runId}`           | Get a workflow run                              | `project:read`  |
| GET   | `/v1/projects/{projectId}/runs`                   | List workflow runs                              | `project:read`  |
| GET   | `/v1/projects/{projectId}/runs/{runId}/config`    | Get the settings at the start of a workflow run | `project:read`  |
| PATCH | `/v1/projects/{projectId}/runs/{runId}`           | Set or clear the deadline of a workflow run     | `project:write` |
| PUT   | `/v1/projects/{projectId}/runs/{runId}/approvers` | Reassign the reviewers of a workflow run        | `project:write` |
| POST  | `/v1/projects/{projectId}/runs/{runId}/cancel`    | Cancel a workflow run                           | `project:run`   |
| GET   | `/v1/projects/{projectId}/runs/{runId}/resume`    | Get the resume options of a closed workflow run | `project:read`  |
| POST  | `/v1/projects/{projectId}/runs/{runId}/resume`    | Resume a closed workflow run                    | `project:run`   |

### POST`/v1/projects/{projectId}/runs`

Starts a run of a `workflow` project. Calling it for a `cycle` project returns `409 Conflict` (`unsupported_project_type`).

#### Request Headers

| Header            | Required | Description                                                                                                 |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | Required | A duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and \_ . : - only |

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Body

The body can be omitted. If you send one, make it a JSON object. <!-- -->Fields other than the one below are ignored, except that sending config returns 400 Bad Request (invalid\_parameter).

| パラメータ     | 型     | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------- | ----- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload` | `any` | —  | The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. It is converted to a JSON string and attached to the request to the agent of the first step (after a fork, the first step of each lane). The agent receives it as data from outside, not as instructions. Putting a file ID in the request does not attach the file. Omitted or null means no request. Up to 8,000 characters as a JSON string |

There are two limits. If `payload` exceeds 8,000 characters as a JSON string, `400 Bad Request` (`payload_too_large`) is returned. If the whole body exceeds 16 KiB, `413 Payload Too Large` (`body_too_large`) is returned.

<!-- -->

#### Response Fields (201 Created / 200 OK)

| Field      | Type       | Description                                                                                                       |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `runId`    | `string`   | Run ID (UUID). Use it to retrieve run status                                                                      |
| `existing` | `boolean?` | true when an existing run was returned for a resend with the same Idempotency-Key. Not included on the first call |

The first call returns `201 Created`; a resend with the same `Idempotency-Key` returns `200 OK`.

#### Request Example

**Start run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: nightly-batch-20260917" \
-H "Content-Type: application/json" \
-d '{
  "payload": {
    "ticketId": "INC-1024",
    "summary": "Some users cannot log in"
  }
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "nightly-batch-20260917"},
  json={'payload': {'ticketId': 'INC-1024', 'summary': 'Some users cannot log in'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "nightly-batch-20260917",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"payload": {"ticketId": "INC-1024", "summary": "Some users cannot log in"}}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"payload": {"ticketId": "INC-1024", "summary": "Some users cannot log in"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "nightly-batch-20260917")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

> **How Idempotency-Key is handled**
>
> - Keys are matched per project. They do not expire.
> - Resending with the same key returns **the same run** even after the project has been paused, after the concurrent-run limit has been reached, or after that run has finished.
> - If a timeout leaves the outcome unknown, simply resend with the same key. Nothing is run twice.
> - To start a different run, always issue a new key.

Resending with the same key but a different `payload` returns `409 Conflict` (`origin_conflict`).

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `idempotency_key_required`        | The Idempotency-Key header is missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400`  | `idempotency_key_invalid`         | The Idempotency-Key length or character set is invalid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `400`  | `invalid_parameter`               | projectId is not a UUID, or config is sent (this API does not accept it; param is config)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `400`  | `payload_too_large`               | payload exceeds 8,000 characters as a JSON string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `400`  | `invalid_body`                    | The request body is malformed JSON or is not a JSON object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `413`  | `body_too_large`                  | The request body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `415`  | `unsupported_media_type`          | A request body is sent with a Content-Type other than application/json                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `insufficient_scope`              | The project:run scope is missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `404`  | `project_not_found`               | The project does not exist or is not accessible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `400`  | `approvers_required`              | An enabled review step has no reviewers configured                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `409`  | `unsupported_project_type`        | A cycle project was specified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `409`  | `project_inactive`                | The project is not active (paused or archived)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `principal_suspended`             | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `start_step_in_branch_lane`       | The start step is in a lane of a branch step. Set the start step of the time trigger to a step outside the lanes of branch steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `409`  | `definition_pending`              | The first definition of the project is waiting for approval, so it cannot run yet. Start it after an approver (another owner or an administrator of the organization) approves it in the product screen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409`  | `relink_required`                 | The project cannot be started or resumed until the references that were not found during import are reconnected. The remaining references appear in the project's relink and in the placements' relink. To clear the references that refuse a start: for rows whose kind is "agent", place the agent again (POST /v1/projects/{projectId}/placements); for rows whose kind is "connector", save the connector again on the product screen; for the placements' relink (playbooks and skills that the placed agent points to but were not found), save the agent again with a spec (PATCH /v1/agents/{agentId}; an update that does not send spec does not clear them). Rows whose blocking is false are items to set up again if needed and do not refuse runs; they can be cleared with DELETE /v1/projects/{projectId}/relink, but clearing them alone does not make the project startable |
| `409`  | `branch_ai_unavailable`           | Branch steps that ask AI cannot run in this environment. Ask an administrator to set up the AI decision for branch steps, or disable those steps in the product screen, then start a new run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `automation_dlp_enabled`          | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration. Until then, a run can start only after the external automation steps are disabled or removed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `automation_destination_missing`  | The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step. If no destinations are listed, ask an administrator                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `automation_destination_inactive` | The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `admin_stopped`                   | An administrator has stopped the project. Ask an administrator to resume it (this API cannot resume it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409`  | `unsupported_runtime`             | The project cannot run in this configuration, for example because agent runtimes are mixed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `409`  | `origin_conflict`                 | A different payload was sent with the same Idempotency-Key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `429`  | `too_many_active_runs`            | The project already has the maximum number of runs (3 in total) that are running or awaiting review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### GET`/v1/projects/{projectId}/runs/{runId}`

Retrieves the status of a run. Besides runs started through the API (`POST /v1/projects/{projectId}/runs`), runs started <!-- -->from the UI, by email, or on a schedule<!-- --> can also be retrieved. `cycle` projects do not create runs, so they are out of scope for this endpoint.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `runId`     | `string` | 必須 | Run ID (UUID)     |

#### Request Example

**Get run**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                             | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`                           | `string`         | Run ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `status`                          | `string`         | Run state. One of "running" (running), "waiting\_gate" (awaiting review), "closed\_done" (completed), "closed\_rejected" (ended by rejection), "closed\_failed" (ended by failure) or "cancelled" (cancelled). Any value other than "running" and "waiting\_gate" means the run has ended. However, when an owner or operator (including people with the organization operations role) resumes a "closed\_rejected" or "closed\_failed" run, the same run returns to "running" (endedAt also returns to null) |
| `originType`                      | `string \| null` | How the run started. One of "manual" (started from the UI), "api" (started through the API), "mail" (started by email) or "cron" (scheduled)                                                                                                                                                                                                                                                                                                                                                                  |
| `originRef`                       | `string \| null` | A reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it                                                                                                                                                                                                                                                                                                                                                                                |
| `currentStepId`                   | `string \| null` | ID (UUID) of the step in progress. While the run proceeds in separate lanes, the ID of the step before the branch. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain                                                                                                                                                                                                                                                                              |
| `startedByRef`                    | `string \| null` | Who or what started the run. See the "Who started the run" table below                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `actorLabel`                      | `string \| null` | Display name of a starter that is not a user (the system integration name or the sender address of an email). null otherwise                                                                                                                                                                                                                                                                                                                                                                                  |
| `startedAt`                       | `string \| null` | Start time (ISO 8601). null before it starts                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `endedAt`                         | `string \| null` | End time (ISO 8601). null before it ends. It returns to null when a closed run is resumed                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `summary`                         | `string \| null` | For a completed run, the output of the last completed step that recorded an output (first 2,000 characters). null if there is no such step and for a run that has not completed. null for a person with the organization operations role who does not take part in the project                                                                                                                                                                                                                                |
| `runtimeKind`                     | `string \| null` | Kind of runtime ("autonomous"). May be null for older runs                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `cancelRequestedAt`               | `string \| null` | Time (ISO 8601) when cancellation was requested. null if not requested                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `deadlineAt`                      | `string \| null` | Deadline of the workflow run (ISO 8601). null if it has no deadline                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `configRevision`                  | `number \| null` | Revision of the case configuration (Marketplace edition runs only). null for SaaS runs                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `steps`                           | `array`          | Records of the step runs, in the order they were recorded                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].runStepId`               | `string`         | ID of the step run (starts with "rs:")                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `steps[].stepId`                  | `string \| null` | Step ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].placementId`             | `string \| null` | ID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].executionId`             | `string \| null` | ID of the agent execution. Set once the agent starts running. null for an external automation step                                                                                                                                                                                                                                                                                                                                                                                                            |
| `steps[].conversationId`          | `string \| null` | ID of the conversation of the agent execution. Set once the agent starts running                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `steps[].status`                  | `string`         | One of "pending" (waiting to run), "running" (running), "waiting\_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)                                                                                                                                                                                                                                                                                                                                                            |
| `steps[].attempt`                 | `number \| null` | Retry count within the same visit (starting at 1). It also increases when a closed run is resumed and when the Agent is relaunched after a connection confirmation is approved                                                                                                                                                                                                                                                                                                                                |
| `steps[].lane`                    | `string \| null` | ID of the lane the step belongs to. "main" for steps that are not in a separate lane                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `steps[].scheduledAt`             | `string \| null` | When the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].startedAt`               | `string \| null` | Start time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `steps[].endedAt`                 | `string \| null` | End time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].outputSummary`           | `string \| null` | Summary of the step output. null for a person with the organization operations role who does not take part in the project ("cancelled" for a step closed by cancellation is kept)                                                                                                                                                                                                                                                                                                                             |
| `steps[].outcome`                 | `string \| null` | Result of the agent execution or of the send of an external automation step. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result                                                                                                                                                                                                                                                                                                          |
| `steps[].reasonCode`              | `string \| null` | Reason code for the result. "branch\_undecided" when a branch could not decide and a person is asked to choose; "branch\_not\_selected" for a step in a lane the branch did not choose                                                                                                                                                                                                                                                                                                                        |
| `steps[].held`                    | `boolean`        | Whether the step is held because the project is paused and is waiting to resume                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].visit`                   | `number \| null` | Which visit to this step this is (increases with send-backs). null for rows without this record                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].reworkReason`            | `string \| null` | Reason for the send-back                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `steps[].gateFor`                 | `string \| null` | For a review row, the step run (runStepId) it was raised for                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].routedFrom`              | `string \| null` | When steps were skipped by choosing a destination, the step run (runStepId) that chose it                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].late`                    | `string \| null` | Why a result that arrived late was not used to advance the run                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].gate`                    | `object \| null` | Summary of the review. Set on review step rows and on connection confirmation wait rows (gateKind is "connection"). null for other rows                                                                                                                                                                                                                                                                                                                                                                       |
| `steps[].gate.decision`           | `string \| null` | One of "proceed", "send\_back" or "reject". null if not decided yet                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].gate.waitSource`         | `string \| null` | What the review waits for. "human" (a person's decision) or "external" (an external condition)                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].resumeCommandId`         | `string \| null` | The commandId used when this row was started by resuming a closed run. It is set on the rows started by that resume (the step chosen and the other lanes started again). Otherwise null                                                                                                                                                                                                                                                                                                                       |
| `steps[].resumeReason`            | `string \| null` | The reason for resuming a closed run. It is set on the same rows as resumeCommandId. Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].supersededBy`            | `string \| null` | "resume" when a row left over from the previous round was closed by resuming a closed run. Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].gateKind`                | `string \| null` | "connection" for a connection confirmation wait row (a row created when the Agent stops before using a connector that requires human confirmation). null otherwise                                                                                                                                                                                                                                                                                                                                            |
| `steps[].connectionConfirmOf`     | `string \| null` | For a row relaunched after a connection confirmation is approved, the ID of that work item (workItemId). null otherwise                                                                                                                                                                                                                                                                                                                                                                                       |
| `steps[].handoff`                 | `object \| null` | The values and files this step's execution passed to the next step. null when the step has no values and file roles for the next step (outputConfig). Not shown to people who cannot see the content                                                                                                                                                                                                                                                                                                          |
| `steps[].handoff.values`          | `object`         | Value name → the returned text (up to 1,000 characters each)                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].handoff.files`           | `object`         | Role name → { filename } (the file name of the file with that role)                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].handoff.missing[]`       | `object[]`       | What did not arrive: name (the value or role name) and reason ("not\_returned" (the agent did not return it) / "file\_not\_found" (not among the output files))                                                                                                                                                                                                                                                                                                                                               |
| `steps[].handoff.truncated`       | `string[]`       | Names of values cut at 1,000 characters. \[] when none                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `plannedPlacements`               | `array`          | Order of steps and placements planned to run, based on the configuration when the run started                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `plannedPlacements[].stepId`      | `string \| null` | Step ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `plannedPlacements[].placementId` | `string \| null` | Placement ID (UUID). null for review steps and steps without an agent                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lanes`                           | `array`          | Status of each lane after the branch. An empty array before the branch and for runs that do not use lanes                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lanes[].laneId`                  | `string`         | Lane ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lanes[].name`                    | `string \| null` | Lane name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lanes[].position`                | `number \| null` | Lane order (starting at 1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lanes[].state`                   | `string`         | One of "running" (running), "waiting\_gate" (awaiting review), "arrived" (waiting to join) or "closed" (ended)                                                                                                                                                                                                                                                                                                                                                                                                |
| `lanes[].currentStepId`           | `string \| null` | ID (UUID) of the step in progress in that lane. null for a lane waiting to join. For a lane that has ended, the ID of its last step may remain                                                                                                                                                                                                                                                                                                                                                                |
| `lanes[].arrived`                 | `boolean`        | Whether the lane has reached the join point                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

The fields are the same regardless of the token used for the call (an application or a system integration).

##### Who started the run

| Started by                                                                    | startedByRef                                                                                                       | actorLabel                                       |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| A user (from the UI, through the API, or by email sent from a member address) | User ID                                                                                                            | null                                             |
| A system integration                                                          | "client:" followed by the Client ID of the system integration. "system:federation-api" if the Client ID is unknown | Name of the system integration (null if unknown) |
| Email sent from an address that is not a member                               | "mail:" followed by a hash of the sender                                                                           | Sender address                                   |
| A schedule                                                                    | null                                                                                                               | null                                             |

For runs started by a system integration before 2026-09-25, `startedByRef` is null.

#### Response Example

<!-- -->

<!-- -->

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "deadlineAt": null,
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null,
      "resumeCommandId": null,
      "resumeReason": null,
      "supersededBy": null,
      "gateKind": null,
      "connectionConfirmOf": null,
      "handoff": null
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}
```

#### Error Responses

| Status | code                 | Description                                                              |
| ------ | -------------------- | ------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or runId is not a UUID                                         |
| `403`  | `insufficient_scope` | The project:read scope is missing                                        |
| `404`  | `run_not_found`      | The run does not exist, belongs to another project, or is not accessible |

### GET`/v1/projects/{projectId}/runs`

Lists workflow runs, newest start first. Up to the latest 100 are returned, and the next page (`cursor`) cannot be read. For a cycle project, the list is empty.

#### Query Parameters

| Parameter      | Type      | Default | Description                                                         |
| -------------- | --------- | ------- | ------------------------------------------------------------------- |
| `limit`        | `integer` | `50`    | Number of items (1-100)                                             |
| `placement_id` | `string`  | `—`     | Filter to workflow runs with steps handled by this placement (UUID) |

#### Request Example

**List runs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field     | Type      | Description                                                                                                                  |
| --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `runs`    | `array`   | Array of workflow runs. The fields of an item are the same as Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}) |
| `hasMore` | `boolean` | When limit is 99 or less, whether there are more. When limit is 100, true when 100 items are returned (there may be no more) |

Workflow runs older than the latest 100 cannot be read with this list. Find the `runId` in the execution history (`GET /v1/projects/{projectId}/executions`, which supports the next page), and read it with Get a Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}`). Steps that have not started and steps waiting for a review do not appear in the execution history, so an old workflow run in which no step has started cannot be found.

#### Response Example

```json
{
  "runs": [
    {
      "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
      "status": "running",
      "originType": "api",
      "originRef": "nightly-batch-20260917",
      "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "actorLabel": null,
      "startedAt": "2026-09-17T01:30:00.000Z",
      "endedAt": null,
      "summary": null,
      "runtimeKind": "autonomous",
      "cancelRequestedAt": null,
      "deadlineAt": null,
      "configRevision": null,
      "steps": [
        {
          "runStepId": "rs:1042",
          "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
          "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
          "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
          "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
          "status": "running",
          "attempt": 1,
          "lane": "main",
          "scheduledAt": null,
          "startedAt": "2026-09-17T01:30:01.000Z",
          "endedAt": null,
          "outputSummary": null,
          "outcome": null,
          "reasonCode": null,
          "held": false,
          "visit": 1,
          "reworkReason": null,
          "gateFor": null,
          "routedFrom": null,
          "late": null,
          "gate": null,
          "resumeCommandId": null,
          "resumeReason": null,
          "supersededBy": null,
          "gateKind": null,
          "connectionConfirmOf": null,
          "handoff": null
        }
      ],
      "plannedPlacements": [
        {
          "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
          "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8"
        },
        {
          "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90",
          "placementId": null
        }
      ],
      "lanes": []
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                                 |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId or placement\_id is not a UUID, placement\_id and placementId have different values, or limit is not an integer between 1 and 100 |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                                           |
| `403`  | `forbidden`          | Called with a system integration token                                                                                                      |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                                          |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                                         |

### GET`/v1/projects/{projectId}/runs/{runId}/config`

Gets the settings at the start of a workflow run (steps, <!-- -->lanes, <!-- -->placements, and connectors). These do not change even if the project's settings are changed later (only `connectionId` of the connectors is resolved from the current connector information).

#### Request Example

**Get run config**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field           | Type             | Description                                                                                                                                                                                                                                                                                                                                                     |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`         | `string`         | ID of the workflow run                                                                                                                                                                                                                                                                                                                                          |
| `takenAt`       | `string \| null` | When the settings were copied (ISO 8601)                                                                                                                                                                                                                                                                                                                        |
| `steps`         | `array \| null`  | The steps at that time. Same fields as Step Fields (without digest; fields not in the copy are null; for an external automation step, automationConfig is included, and for a step run by an Agent ("ai"), outputConfig is included; for a branch step, branchConfig is included)                                                                               |
| `lanes`         | `array \| null`  | The lanes at that time (id, name, parentLaneId, and stepIds). In a copy without lanes, all steps are in one "main" lane and name is null                                                                                                                                                                                                                        |
| `forks`         | `array \| null`  | The splits at that time (id, afterStepId, laneIds, and joinId)                                                                                                                                                                                                                                                                                                  |
| `joins`         | `array \| null`  | The joins at that time (id, mode, laneIds, and nextStepId)                                                                                                                                                                                                                                                                                                      |
| `placements`    | `array \| null`  | The placements at that time (placementId, agentId, name, goal, guardrail, skills, playbookId, playbookName, runtimeConfigs, libraryBindings, sweeps, stepIds, and instructionAddendum). runtimeConfigs and libraryBindings have the same form as the placement fields. goal, guardrail, skills, playbookId, and instructionAddendum are the values at the start |
| `connectors`    | `array \| null`  | The connectors at that time (kind, connectionId, name, and ledgerEnabled). name is the name at the start. connectionId is resolved from the current connector information (null if disabled or deleted in the admin console, or if it could not be checked)                                                                                                     |
| `sendBackLimit` | `number \| null` | Maximum number of send-backs                                                                                                                                                                                                                                                                                                                                    |

For a workflow run without a copy of the settings, or whose copy cannot be read, everything other than `runId` is null.

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "takenAt": "2026-09-17T01:30:00.000Z",
  "steps": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 1,
      "name": "Amount check",
      "description": "Matches invoice amounts against line items",
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null
    },
    {
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "position": 2,
      "name": "Difference check",
      "description": null,
      "enabled": true,
      "defaultZone": "gate",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "position": 3,
      "name": "Difference report",
      "description": null,
      "enabled": true,
      "defaultZone": "ai",
      "automationConfig": null,
      "branchConfig": null,
      "reworkToStepId": null,
      "gateConfig": null,
      "gateKind": null,
      "schedule": null,
      "scheduleNextFireAt": null,
      "onDenied": null,
      "onDegraded": null,
      "outcomeRoutes": null,
      "laneId": null,
      "placementExecution": null,
      "outputConfig": null
    }
  ],
  "lanes": [
    {
      "id": "main",
      "name": null,
      "parentLaneId": null,
      "stepIds": [
        "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
      ]
    }
  ],
  "forks": [],
  "joins": [],
  "placements": [
    {
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
      "name": "Accounting Agent",
      "goal": "Match invoice amounts against line items and report differences",
      "guardrail": "Do not change amounts",
      "skills": [
        {
          "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
          "name": "Invoice reading"
        }
      ],
      "playbookId": null,
      "playbookName": null,
      "runtimeConfigs": [
        {
          "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "runtimeConfig": null
        }
      ],
      "libraryBindings": [],
      "sweeps": [],
      "stepIds": [
        "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
      ],
      "instructionAddendum": null
    }
  ],
  "connectors": [],
  "sendBackLimit": 3
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                 |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId or runId is not a UUID                                                                                            |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                           |
| `403`  | `forbidden`          | Called with a system integration token                                                                                      |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                          |
| `404`  | `run_not_found`      | The workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project |

### PATCH`/v1/projects/{projectId}/runs/{runId}`

Sets or clears the deadline of a workflow run. When the deadline passes, a row for the workflow run past its deadline (`run_deadline_overdue`) appears in the [queue](#queue). Owners and operators (including people with the organization operations role) can call this API. Only workflow runs that have not ended (`status` is `"running"` or `"waiting_gate"`) can be changed.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Body

| Field        | Type             | Required | Description                                                              |
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------ |
| `deadlineAt` | `string \| null` | Yes      | Deadline (an ISO 8601 date-time in the future). null clears the deadline |

Resending the same value gives the same result.

#### Request Example

**Set run deadline**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "deadlineAt": "2026-11-20T09:00:00.000Z"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  headers={"Authorization": f"Bearer {token}"},
  json={'deadlineAt': '2026-11-20T09:00:00.000Z'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"deadlineAt": "2026-11-20T09:00:00.000Z"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"deadlineAt": "2026-11-20T09:00:00.000Z"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

The workflow run after the change. The fields are the same as Get a Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}`).

If reading the workflow run back after changing the deadline fails, `502 Bad Gateway` (`upstream_connection_error`) is returned. The deadline may already have changed, so check `deadlineAt` with Get a Workflow Run before resending.

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "deadlineAt": "2026-11-20T09:00:00.000Z",
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null,
      "resumeCommandId": null,
      "resumeReason": null,
      "supersededBy": null,
      "gateKind": null,
      "connectionConfirmOf": null,
      "handoff": null
    }
  ],
  "plannedPlacements": [
    {
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8"
    },
    {
      "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90",
      "placementId": null
    }
  ],
  "lanes": []
}
```

#### Error Responses

| Status | code                        | Description                                                                                                                 |
| ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`         | projectId or runId is not a UUID, or deadlineAt is missing, is not an ISO 8601 date-time, or is not in the future           |
| `400`  | `invalid_body`              | The body is malformed JSON or not a JSON object                                                                             |
| `403`  | `insufficient_scope`        | The project:write scope is missing                                                                                          |
| `403`  | `forbidden`                 | Called with a system integration token                                                                                      |
| `403`  | `operator_only`             | A member who is neither an owner nor an operator and does not have the organization operations role                         |
| `403`  | `sso_required`              | The user does not sign in with SSO                                                                                          |
| `404`  | `run_not_found`             | The workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project |
| `409`  | `invalid_state`             | The workflow run has ended                                                                                                  |
| `413`  | `body_too_large`            | The body exceeds 16 KiB                                                                                                     |
| `415`  | `unsupported_media_type`    | The Content-Type of the body is not application/json                                                                        |
| `502`  | `upstream_connection_error` | Reading the workflow run back after changing the deadline failed (check with Get a Workflow Run before resending)           |

### PUT`/v1/projects/{projectId}/runs/{runId}/approvers`

Replaces, all at once, the reviewers of the review requests of a workflow run that have not been decided yet<!-- --> (including connection confirmations)<!-- -->. Owners and operators (including people with the organization operations role) can call this API. Only workflow runs that have not ended can be changed. The review request notification is sent only to people who newly become reviewers.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Body

| Field             | Type     | Required | Description                                                                                                                           |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `approverUserIds` | `array`  | Yes      | User IDs of the new reviewers (1 to 50 people; current members of the project only; up to 128 characters each; each person only once) |
| `commandId`       | `string` | Yes      | A value to identify resends (8 to 128 characters of letters, digits, and \_ . : -)                                                    |

- If you resend the same reviewers with the same `commandId`, the same result as the first request is returned. Sending different reviewers with the same `commandId` returns `409 Conflict` (`command_conflict`).
- For a reassignment with very many reviewers or target review requests (for example, 50 reviewers), a resend with the same `commandId` cannot compare the reviewers, so 200 is returned as the result of the first request and `workItemIds` may be empty. Check the result with Get a Workflow Run and Get a Review Request.

#### Request Example

**Reassign run approvers**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "approverUserIds": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ],
  "commandId": "reassign-20261118-0001"
}'
```

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers",
  headers={"Authorization": f"Bearer {token}"},
  json={'approverUserIds': ['f47ac10b-58cc-4372-a567-0e02b2c3d479'], 'commandId': 'reassign-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"approverUserIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], "commandId": "reassign-20261118-0001"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"approverUserIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], "commandId": "reassign-20261118-0001"}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field             | Type     | Description                                                      |
| ----------------- | -------- | ---------------------------------------------------------------- |
| `runId`           | `string` | ID of the workflow run                                           |
| `approverUserIds` | `array`  | User IDs of the reviewers after the change (the values you sent) |
| `workItemIds`     | `array`  | IDs of the review requests whose reviewers were replaced         |

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "approverUserIds": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ],
  "workItemIds": [
    "c9d8e7f6-a5b4-4321-8fed-cba098765432"
  ]
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                        |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or runId is not a UUID, approverUserIds is not an array of 1 to 50 user IDs (including an empty ID or an ID longer than 128 characters) or contains the same person twice, or commandId is missing or has the wrong form |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                    |
| `400`  | `approver_not_member`    | approverUserIds includes someone who is not a current member of the project                                                                                                                                                        |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                                                                                                                 |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                             |
| `403`  | `operator_only`          | A member who is neither an owner nor an operator and does not have the organization operations role                                                                                                                                |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                 |
| `404`  | `run_not_found`          | The workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project                                                                                                        |
| `409`  | `invalid_state`          | The workflow run has ended                                                                                                                                                                                                         |
| `409`  | `command_conflict`       | Different reviewers were sent with the same commandId                                                                                                                                                                              |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                            |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                               |

### POST`/v1/projects/{projectId}/runs/{runId}/cancel`

Cancels a workflow run that is running or awaiting review (`status` is `"running"` or `"waiting_gate"`). This is the same as Cancel run on the screen. <!-- -->Owners and operators (including people with the organization operations role), and the person who started the workflow run, can call this API. It can also be called with a system integration token.

When it is cancelled:

- The `status` of the workflow run becomes `"cancelled"` (cancelled).
  <!-- -->
  This cannot be undone, and the workflow run cannot be resumed (only workflow runs closed by a rejection or a failure can be resumed).
- <!-- -->
  Steps in progress are marked failed, and running Agents are told to stop.
  <!-- -->
- Review requests of review steps that have not been decided are withdrawn.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Body

| Field       | Type     | Required | Description                                                                        |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------- |
| `commandId` | `string` | Yes      | A value to identify resends (8 to 128 characters of letters, digits, and \_ . : -) |
| `reason`    | `string` | —        | The reason for canceling (up to 500 characters)                                    |

- If you send it for a workflow run that is not running (after it ended or was cancelled), nothing changes: `200 OK` is returned with `existing` set to `true`. The same applies when you resend after it was cancelled.
- If you send it around the same time as another cancel or the end of the workflow run, the choice between `202 Accepted` and `200 OK` and the value of `existing` may not match what actually happened. Check the result with `status` of Get a Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}`).
- `504 Gateway Timeout` does not mean "it was not cancelled". Resend with the same `commandId`, or check `status` with Get a Workflow Run.

#### Request Example

**Cancel run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "commandId": "cancel-20261118-0001",
  "reason": "Because an error in the input data was noticed"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
  headers={"Authorization": f"Bearer {token}"},
  json={'commandId': 'cancel-20261118-0001', 'reason': 'Because an error in the input data was noticed'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (202 Accepted / 200 OK)

`202 Accepted` when this request cancelled the workflow run, and `200 OK` when it did not.

| Field               | Type             | Description                                                                                   |
| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `runId`             | `string`         | ID of the workflow run                                                                        |
| `status`            | `string`         | The status of the workflow run after the request ("cancelled" when it was cancelled)          |
| `cancelRequestedAt` | `string \| null` | When the cancel was accepted (ISO 8601). null for a workflow run that was not cancelled       |
| `existing`          | `boolean`        | true when this request did not newly cancel the workflow run (always false with 202 Accepted) |

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "cancelled",
  "cancelRequestedAt": "2026-11-18T05:12:30.000Z",
  "existing": false
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                           |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or runId is not a UUID, commandId is missing or has the wrong form, or reason is not a string or is longer than 500 characters              |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                       |
| `403`  | `insufficient_scope`     | The project:run scope is missing                                                                                                                      |
| `403`  | `operator_only`          | A member who is neither an owner nor an operator and does not have the organization operations role tried to cancel a workflow run they did not start |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                    |
| `404`  | `run_not_found`          | The workflow run does not exist, belongs to another project, or you are not a member of the project                                                   |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                               |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                  |

<!-- -->

### GET`/v1/projects/{projectId}/runs/{runId}/resume`

Gets whether a workflow run that was closed by a rejection or a failure (`status` is `"closed_rejected"` or `"closed_failed"`) can be resumed, and the steps it can be resumed from. Owners and operators (including people with the organization operations role) can call this API (it reads, but a member who is neither an owner nor an operator and does not have the organization operations role gets `403 Forbidden` (`operator_only`)). A workflow run that is not closed, or that ended by completion or cancellation, also returns `200 OK` with `resumable` set to `false`.

- The steps it can be resumed from are the steps executed by an Agent and the external automation steps that are in the same lane as the step that caused the close (for a rejection, the review step that was rejected last; for a failure, the step executed by an Agent or the external automation step that failed last), up to and including that step. Only steps that are not disabled are included, and a step executed by an Agent must have had an Agent placed when the workflow run started. In `"main"`, they cannot cross between before the fork and after the join.
- The default step (`defaultStepId`) is the step that caused the close if it is a step executed by an Agent or an external automation step, or, if it is a review step, the nearest earlier candidate step.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Example

**Get run resume options**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                       | Type             | Description                                                                                                                                                                                                                                            |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `runId`                     | `string`         | ID of the workflow run                                                                                                                                                                                                                                 |
| `status`                    | `string`         | The current status of the workflow run                                                                                                                                                                                                                 |
| `endedAt`                   | `string \| null` | When it ended (ISO 8601)                                                                                                                                                                                                                               |
| `resumable`                 | `boolean`        | Whether it can be resumed                                                                                                                                                                                                                              |
| `reason`                    | `string \| null` | Why it cannot be resumed: "status\_not\_resumable" (not a workflow run closed by a rejection or a failure) / "run\_not\_resumable" (the settings at its start are not kept) / "no\_resume\_step" (no step to resume from). null when it can be resumed |
| `cause`                     | `object \| null` | Why it was closed. null when the step that caused it is not known                                                                                                                                                                                      |
| `cause.kind`                | `string`         | "rejected" (rejected at a review step) / "failed" (a step executed by an Agent or an external automation step failed)                                                                                                                                  |
| `cause.stepId`              | `string`         | ID of the step that caused it                                                                                                                                                                                                                          |
| `cause.stepName`            | `string`         | Name of the step that caused it                                                                                                                                                                                                                        |
| `cause.comment`             | `string \| null` | The reason for the rejection (for a rejection, when a reason was written)                                                                                                                                                                              |
| `cause.outcome`             | `string \| null` | The outcome of the step that failed (for a failure)                                                                                                                                                                                                    |
| `cause.reasonCode`          | `string \| null` | The reason code of the step that failed (for a failure)                                                                                                                                                                                                |
| `defaultStepId`             | `string \| null` | ID of the default step to resume from. null when it cannot be resumed                                                                                                                                                                                  |
| `candidates`                | `array`          | The steps it can be resumed from (in step order). An empty array when it cannot be resumed                                                                                                                                                             |
| `candidates[].stepId`       | `string`         | ID of the step. Put it in fromStepId when resuming                                                                                                                                                                                                     |
| `candidates[].name`         | `string`         | Name of the step                                                                                                                                                                                                                                       |
| `candidates[].position`     | `number \| null` | Position of the step                                                                                                                                                                                                                                   |
| `candidates[].laneId`       | `string \| null` | ID of the lane of the step (null for steps in "main")                                                                                                                                                                                                  |
| `candidates[].laneName`     | `string \| null` | Name of the lane (null for "main" and for lanes without a name)                                                                                                                                                                                        |
| `candidates[].lanePosition` | `number \| null` | Position among the lanes other than "main" (from 1; null for "main")                                                                                                                                                                                   |

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "closed_failed",
  "endedAt": "2026-11-18T02:10:00.000Z",
  "resumable": true,
  "reason": null,
  "cause": {
    "kind": "failed",
    "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "stepName": "Amount check",
    "comment": null,
    "outcome": "failed",
    "reasonCode": null
  },
  "defaultStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "candidates": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "name": "Amount check",
      "position": 1,
      "laneId": null,
      "laneName": null,
      "lanePosition": null
    }
  ]
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                 |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId or runId is not a UUID                                                                                            |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                           |
| `403`  | `forbidden`          | Called with a system integration token                                                                                      |
| `403`  | `operator_only`      | A member who is neither an owner nor an operator and does not have the organization operations role                         |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                          |
| `404`  | `run_not_found`      | The workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project |

### POST`/v1/projects/{projectId}/runs/{runId}/resume`

Runs a workflow run that was closed by a rejection or a failure again from the step you choose, as the same workflow run. Owners and operators (including people with the organization operations role) can call this API. Check the steps it can be resumed from in `candidates` of Get the Resume Options of a Closed Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}/resume`).

When it is resumed:

- The `status` of the same workflow run returns to `"running"`, and `endedAt` returns to null.
- Step rows of the next round (`attempt`) are added from the step you chose. When it is resumed from a step in a lane, the other lanes that had arrived at the join stay arrived, and the other lanes that were stopped when it was closed start again from the step where they stopped.
- The step rows left over from the previous round (`status` is `"pending"`, `"running"`, or `"waiting_gate"`) become `"failed"`, and their `supersededBy` becomes `"resume"`. The results of the previous round are kept.
- The reason for resuming is kept in `resumeReason` of the step rows started by this resume, and you can read it with Get a Workflow Run. The audit log records "Run resumed" (`run.resumed`), but not the reason.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Body

| Field            | Type     | Required | Description                                                                                                                              |
| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `fromStepId`     | `string` | Yes      | ID of the step to resume from (UUID). One of candidates\[].stepId of Get the Resume Options of a Closed Workflow Run                     |
| `reason`         | `string` | Yes      | The reason for resuming (up to 1000 characters, counting leading and trailing whitespace; cannot be only whitespace)                     |
| `expectedStatus` | `string` | Yes      | The current status: "closed\_rejected" or "closed\_failed" (the same value as status of Get the Resume Options of a Closed Workflow Run) |
| `commandId`      | `string` | Yes      | A value to identify resends (8 to 128 characters of letters, digits, and \_ . : -)                                                       |

- If you resend the same content with the same `commandId`, it is not resumed again, and the same `stepId`, `attempt`, and `runStepIds` as the first request are returned. `status` is the current status of the workflow run at the time of the resend. Sending different content with the same `commandId` returns `409 Conflict` (`command_conflict`).
- If the `expectedStatus` you sent differs from the current status, `409 Conflict` (`status_changed`) is returned (for example, when someone else resumed it first). Get the workflow run and the resume options again, and if it can still be resumed, send the request again with that status and those options.

#### Request Example

**Resume run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "reason": "Because the input data was corrected",
  "expectedStatus": "closed_failed",
  "commandId": "resume-20261118-0001"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume",
  headers={"Authorization": f"Bearer {token}"},
  json={'fromStepId': '5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819', 'reason': 'Because the input data was corrected', 'expectedStatus': 'closed_failed', 'commandId': 'resume-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "reason": "Because the input data was corrected", "expectedStatus": "closed_failed", "commandId": "resume-20261118-0001"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"fromStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819", "reason": "Because the input data was corrected", "expectedStatus": "closed_failed", "commandId": "resume-20261118-0001"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/resume", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field        | Type             | Description                                                                                                                                                                 |
| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`      | `string`         | ID of the workflow run                                                                                                                                                      |
| `status`     | `string`         | The status of the workflow run after it was resumed                                                                                                                         |
| `stepId`     | `string`         | ID of the step it was resumed from                                                                                                                                          |
| `attempt`    | `number \| null` | The round of the row of the step it was resumed from                                                                                                                        |
| `runStepIds` | `array`          | IDs of the step rows started by this resume (rs:\<number>; the step you chose and the other lanes started again). The same form as steps\[].runStepId of Get a Workflow Run |

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "attempt": 2,
  "runStepIds": [
    "rs:1051"
  ]
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                           |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId, runId, or fromStepId is not a UUID, reason is missing, not a string, longer than 1000 characters, or only whitespace, expectedStatus is not "closed\_rejected" / "closed\_failed", or commandId is missing or has the wrong form                                           |
| `400`  | `invalid_body`                    | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                       |
| `400`  | `invalid_resume_step`             | fromStepId is not a step it can be resumed from                                                                                                                                                                                                                                       |
| `403`  | `insufficient_scope`              | The project:run scope is missing                                                                                                                                                                                                                                                      |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                                                                                                                                |
| `403`  | `operator_only`                   | A member who is neither an owner nor an operator and does not have the organization operations role                                                                                                                                                                                   |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                                                                                                                                    |
| `404`  | `run_not_found`                   | The workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project                                                                                                                                                           |
| `409`  | `status_changed`                  | expectedStatus differs from the current status                                                                                                                                                                                                                                        |
| `409`  | `run_not_resumable`               | A workflow run whose settings at its start are not kept                                                                                                                                                                                                                               |
| `409`  | `project_inactive`                | The project is not active (paused or archived)                                                                                                                                                                                                                                        |
| `409`  | `principal_suspended`             | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                                                                                                                 |
| `409`  | `automation_dlp_enabled`          | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration. Until then, a run can start only after the external automation steps are disabled or removed                                                          |
| `409`  | `automation_destination_missing`  | The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step. If no destinations are listed, ask an administrator |
| `409`  | `automation_destination_inactive` | The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step |
| `409`  | `admin_stopped`                   | An administrator has stopped the project. Ask an administrator to resume it                                                                                                                                                                                                           |
| `409`  | `unsupported_runtime`             | An Agent of a kind this service cannot run is placed                                                                                                                                                                                                                                  |
| `409`  | `command_conflict`                | Different content was sent with the same commandId                                                                                                                                                                                                                                    |
| `413`  | `body_too_large`                  | The body exceeds 16 KiB                                                                                                                                                                                                                                                               |
| `415`  | `unsupported_media_type`          | The Content-Type of the body is not application/json                                                                                                                                                                                                                                  |
| `429`  | `too_many_active_runs`            | The project already has the maximum number of runs (3 in total) that are running or awaiting review                                                                                                                                                                                   |

## Executions

An execution is <!-- -->one run of an Agent or one send of an external automation step<!-- -->. Executions are listed in the execution history on the screen, and opening one shows the run record (when sweeps that changed nothing continue, the screen shows them as one row; this API returns them one by one without grouping). There are executions of workflow steps (`kind` is `"run_step"`; `executionId` has the form `rs:<number>`) and executions of cycle sweeps (`"sweep"`; `executionId` is a UUID).

### Endpoint List

| メソッド | エンドポイント                                                        | 説明                                 | Scope (SaaS)   |
| ---- | -------------------------------------------------------------- | ---------------------------------- | -------------- |
| GET  | `/v1/projects/{projectId}/executions`                          | Get the execution history          | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}`            | Get the result of an execution     | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/operations` | Get the list of tool calls         | `project:read` |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/timeline`   | Get the timeline of an execution   | `project:read` |
| POST | `/v1/projects/{projectId}/executions/{executionId}/rerun`      | Run a failed sweep execution again | `project:run`  |

### Outcome Values

The values of `outcome`. For what the screen shows, see the [Results Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/results-ref.md).

| Value        | Shown on the screen        |
| ------------ | -------------------------- |
| `completed`  | Completed                  |
| `incomplete` | Failed (reported by agent) |
| `failed`     | Failed                     |
| `timeout`    | Timed out                  |
| `stopped`    | Failed (stopped)           |
| `denied`     | Not allowed by rules       |
| `skipped`    | Nothing to do              |

For executions that have not finished, and executions that finished without a recorded result (insufficient records), `outcome` is null.

An execution that stopped because the Agent was about to use a connector that requires human confirmation (connection confirmation) has `outcome` `incomplete` and `reasonCode` `connection_confirm_requested` (shown on the screen as "Stopped for connection confirmation"). Such an execution is not counted as a failure (it is not included in `outcome=problems` of the execution history, sweep failures in the [queue](#queue), the completion rate of the [KPIs](#kpi), and so on). The confirmation arrives as a [review request](#workitems).

### GET`/v1/projects/{projectId}/executions`

Gets the execution history, newest start time first. Cursor-based pagination is supported. Steps that have not started and steps waiting for a review are not included.

#### Query Parameters

| Parameter      | Type      | Default | Description                                                                                                                                                                                                                                                                                                                                     |
| -------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`         | `string`  | `—`     | Filter to executions that started at or after this time (ISO 8601)                                                                                                                                                                                                                                                                              |
| `to`           | `string`  | `—`     | Filter to executions that started at or before this time (ISO 8601)                                                                                                                                                                                                                                                                             |
| `placement_id` | `string`  | `—`     | Filter to executions of this placement (UUID)                                                                                                                                                                                                                                                                                                   |
| `step_id`      | `string`  | `—`     | Filter to executions of this step (UUID)                                                                                                                                                                                                                                                                                                        |
| `run_id`       | `string`  | `—`     | Filter to step executions of this workflow run (UUID)                                                                                                                                                                                                                                                                                           |
| `outcome`      | `string`  | `"all"` | Filter by result. Besides the outcome values: "all" (all), "success" (completed), "problems" (incomplete, failed, timeout, stopped, and denied; executions stopped for a connection confirmation are not included), "running" (running), "missing" (insufficient records), or "unmeasured" (finished in a way where completion is not measured) |
| `fix_target`   | `string`  | `—`     | Filter by fix target: "goal", "skill", "handoff", "not\_assigned", "connection", "rule", "guardrail", "external", or "unknown" (the values of envelope.completionReport.fixTarget in the execution result), or "platform" (executions with a platform-side failure)                                                                             |
| `reason_code`  | `string`  | `—`     | Filter to executions whose reason for the outcome (executions\[].reasonCode) matches (for example, connection\_confirm\_requested). Case-sensitive. Starts with a letter and contains only letters, digits, and \_ . : -, up to 64 characters (surrounding whitespace is removed; no filter when empty)                                         |
| `q`            | `string`  | `—`     | Filter by part of the Agent name, the execution UUID, or the conversation ID (up to 200 characters). Cycle executions can be found by executionId. Workflow step executions cannot be found by rs:\<number>; use steps\[].executionId (a UUID) of the workflow run                                                                              |
| `limit`        | `integer` | `50`    | Number of items per page (1-100)                                                                                                                                                                                                                                                                                                                |
| `cursor`       | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                                                                                                                                                                                                                                                                          |

#### Request Example

**List executions**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions?outcome=success&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions",
  headers={"Authorization": f"Bearer {token}"},
  params={"outcome": "success", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions" + "?outcome=success&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions?outcome=success&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                               | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executions`                        | `array`           | Array of executions                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `executions[].executionId`          | `string`          | Execution ID. rs:\<number> for a workflow, and a UUID for a cycle                                                                                                                                                                                                                                                                                                                                                                                 |
| `executions[].kind`                 | `string \| null`  | "run\_step" (a workflow step) or "sweep" (a cycle sweep)                                                                                                                                                                                                                                                                                                                                                                                          |
| `executions[].runId`                | `string \| null`  | ID of the workflow run. null for a cycle                                                                                                                                                                                                                                                                                                                                                                                                          |
| `executions[].stepId`               | `string \| null`  | Step ID                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `executions[].stepName`             | `string \| null`  | Step name                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `executions[].stepPosition`         | `number \| null`  | Position of the step                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `executions[].placementId`          | `string \| null`  | Placement ID                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `executions[].agentName`            | `string \| null`  | Agent name                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `executions[].attempt`              | `number \| null`  | Attempt number (increases when a platform failure is retried. For a workflow step, it also increases when the Agent is relaunched after a connection confirmation is approved. For a cycle, when a periodic sweep ends with an `outcome` of `"failed"` or `"timeout"`, it is retried once as a new execution, whose attempt is 2 (no retry for `"incomplete"`, `"stopped"`, `"denied"`, and so on). Any other relaunch is a new execution with 1) |
| `executions[].lane`                 | `string \| null`  | Lane ID (workflow; "main" when there are no lanes)                                                                                                                                                                                                                                                                                                                                                                                                |
| `executions[].outcome`              | `string \| null`  | Outcome (see "Outcome Values" above)                                                                                                                                                                                                                                                                                                                                                                                                              |
| `executions[].reasonCode`           | `string \| null`  | Reason for the outcome. For a cycle, the reason the execution ended (for example, "guardrail\_blocked"); for a workflow, the reason reported by the step                                                                                                                                                                                                                                                                                          |
| `executions[].resultState`          | `string \| null`  | "terminal" (has a result), "running" (running), "missing" (insufficient record), "unmeasured" (completion not measured), or "not\_applicable" (a row that is not an Agent execution, such as a review step)                                                                                                                                                                                                                                       |
| `executions[].terminal`             | `boolean \| null` | Whether it has finished                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `executions[].startedAt`            | `string \| null`  | Start time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `executions[].endedAt`              | `string \| null`  | End time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `executions[].summary`              | `string \| null`  | Final response of a workflow step (up to 2000 characters). null for a cycle (read it in the execution result). null for a person with the organization operations role who does not take part in the project                                                                                                                                                                                                                                      |
| `executions[].errorMessage`         | `string \| null`  | Error message (cycle)                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `executions[].originType`           | `string \| null`  | How it started. For a workflow, how the workflow run started ("manual", "api", "mail", or "cron"); for a cycle, "cron" (sweep), "mail" (Start by email), or "webhook" (trigger fire)                                                                                                                                                                                                                                                              |
| `executions[].actorLabel`           | `string \| null`  | Display name of a starter that is not a user (the name of a system integration, or the sender address of an email)                                                                                                                                                                                                                                                                                                                                |
| `executions[].gateDecision`         | `string \| null`  | Decision of the review step                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `executions[].conversationId`       | `string \| null`  | ID of the execution conversation (used to read the execution conversation)                                                                                                                                                                                                                                                                                                                                                                        |
| `executions[].fixTarget`            | `string \| null`  | Fix target (same values as envelope.completionReport.fixTarget in the execution result). null when absent                                                                                                                                                                                                                                                                                                                                         |
| `executions[].platformFailure`      | `string \| null`  | Kind of platform-side failure (same values as envelope.platformFailure in the execution result). null when absent                                                                                                                                                                                                                                                                                                                                 |
| `executions[].rerunOf`              | `string \| null`  | For an execution started by rerunning a failed sweep, the ID of the original execution (also, for a sweep execution relaunched after a connection confirmation is approved, the ID of the stopped execution). Otherwise null                                                                                                                                                                                                                      |
| `executions[].automationHttpStatus` | `number \| null`  | For the send of an external automation step, the HTTP status returned by the destination. null on a timeout or when it did not arrive, and for rows that are not external automation                                                                                                                                                                                                                                                              |
| `hasMore`                           | `boolean`         | Whether there is a next page                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cursor`                            | `string`          | Cursor for the next page. Included only when hasMore is true                                                                                                                                                                                                                                                                                                                                                                                      |

#### Response Example

```json
{
  "executions": [
    {
      "executionId": "rs:1842",
      "kind": "run_step",
      "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "stepName": "Amount check",
      "stepPosition": 2,
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "agentName": "Accounting Agent",
      "attempt": 1,
      "lane": "main",
      "outcome": "completed",
      "reasonCode": null,
      "resultState": "terminal",
      "terminal": true,
      "startedAt": "2026-11-18T01:30:05.000Z",
      "endedAt": "2026-11-18T01:34:40.000Z",
      "summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
      "errorMessage": null,
      "originType": "manual",
      "actorLabel": null,
      "gateDecision": null,
      "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "fixTarget": null,
      "platformFailure": null,
      "rerunOf": null,
      "automationHttpStatus": null
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                                                                                                                                                                                                                                                  |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId, placement\_id, step\_id, or run\_id is not a UUID, a snake\_case name and its earlier name have different values, from or to is not an ISO 8601 time, outcome or fix\_target is not one of the values above, reason\_code is not in the form of a reason or was specified more than once, q exceeds 200 characters, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                                                                                                                                                                                                                                                            |
| `403`  | `forbidden`          | Called with a system integration token                                                                                                                                                                                                                                                                                                                       |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                           |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                                                                                                                                                                                                                                                          |

### GET`/v1/projects/{projectId}/executions/{executionId}`

Gets the result of an execution (the run record). An execution of a workflow step can be read with `rs:<number>` from the execution history, and also with `steps[].executionId` (a UUID) of the workflow run. `executionId` in the response is `rs:<number>`.

<!-- -->

#### Path Parameters

| パラメータ         | 型        | 必須 | 説明                                    |
| ------------- | -------- | -- | ------------------------------------- |
| `projectId`   | `string` | 必須 | Project ID (UUID)                     |
| `executionId` | `string` | 必須 | Execution ID (rs:\<number> or a UUID) |

#### Request Example

**Get execution**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

In addition to the fields of an item in the execution history, the following fields are returned. `summary` is up to 2000 characters for a workflow, and for a cycle it is the last message of the conversation as is. For a person with the organization operations role who does not take part in the project, `summary`, `edited`, and `envelope.completionReport.comment` are null, and `artifacts`, `files`, `inputs`, and `inputs` and `writes` of `library` are empty arrays.

| Field                                 | Type              | Description                                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectionConfirmOf`                 | `string \| null`  | For an execution relaunched after a connection confirmation is approved, the ID of that review request (workItemId). Otherwise null                                                                                                                                                                       |
| `edited`                              | `object \| null`  | When the reviewer of a review step edited the output text and proceeded: the edited text, who edited it, when, and the review request. The next step receives the edited text. summary stays as the original output. null if it was not edited                                                            |
| `edited.text`                         | `string`          | The edited text                                                                                                                                                                                                                                                                                           |
| `edited.editedByUserId`               | `string \| null`  | User ID of the person who edited it. null when there is no record                                                                                                                                                                                                                                         |
| `edited.editedAt`                     | `string \| null`  | Date and time it was edited (ISO 8601). null when there is no record                                                                                                                                                                                                                                      |
| `edited.workItemId`                   | `string \| null`  | ID of that review request (workItemId). null when there is no record                                                                                                                                                                                                                                      |
| `billingSteps`                        | `integer \| null` | Number of work steps (same formula as the KPI work steps). Only for finished executions (null while running); 0 for results that are not billable; null when the counts were not recorded                                                                                                                 |
| `envelope`                            | `object \| null`  | Summary of the execution                                                                                                                                                                                                                                                                                  |
| `envelope.counts`                     | `object`          | Numbers of tool calls (toolCalls, readCalls, mutatingSuccess, mutatingFailed, unknownCalls, opaqueCalls, workspaceWrites, mcpCalls, and mcpFailed)                                                                                                                                                        |
| `envelope.completionReport`           | `object \| null`  | Completion report of the Agent (completed, reasonCode, fixTarget, comment, and truncated)                                                                                                                                                                                                                 |
| `envelope.completionReport.fixTarget` | `string \| null`  | What to fix: "goal", "skill", "handoff", "not\_assigned", "connection", "rule", "guardrail", "external", or "unknown". null when there is none                                                                                                                                                            |
| `envelope.completionReport.comment`   | `string \| null`  | Comment of the Agent (up to 2 KB; truncated is true when cut)                                                                                                                                                                                                                                             |
| `envelope.platformFailure`            | `string \| null`  | Kind of platform failure (when the outcome is failed or timeout): "cancelled", "signal\_cancelled", "kill\_timeout", "exception", "invalid\_output", "model\_refusal", "content\_filter", "max\_turns", or "loop\_limit". null when there is none                                                         |
| `envelope.tools`                      | `array`           | Names of the tools called                                                                                                                                                                                                                                                                                 |
| `usedSettings`                        | `object`          | Settings used                                                                                                                                                                                                                                                                                             |
| `usedSettings.manifest`               | `object \| null`  | Distributed skills (skill IDs and version IDs), the playbook, guardrails, and so on. Same as the meta of context.manifest in the execution timeline, with field names as recorded                                                                                                                         |
| `usedSettings.mcp`                    | `object \| null`  | MCP connections (numbers and names of configured, connected, and failed servers, and so on). Same as the meta of runtime.mcp.connected in the execution timeline. null for an execution that does not use MCP                                                                                             |
| `questions`                           | `array`           | Questions from the Agent (eventId, at, kind, optionsCount, optionsTruncated, and answer)                                                                                                                                                                                                                  |
| `questions[].answer`                  | `object \| null`  | Answer (at, eventType, actorKind, actorRef, digest, answerKind, and optionIndex). null when there is no record of an answer                                                                                                                                                                               |
| `gates`                               | `array`           | Review requests (workItemId, title, status, gateDecision, decidedAt, gateMode, decidedByKind, decidedByRef, waitSource, decisionReason, and destinationLabel)                                                                                                                                             |
| `artifacts`                           | `array`           | Artifacts (artifactId, name, path, format, sha256, and size; the content is not included)                                                                                                                                                                                                                 |
| `files`                               | `array`           | Files (filename, filepath, source, isPrimary, createdAt, and mimeType (application/octet-stream when unknown); size when known). Same form as deliverables in the conversation API. Get the content by passing filepath as path to Get the content of a file (GET /v1/projects/{projectId}/files/content) |
| `configuration`                       | `object`          | Execution settings (policyVersion, policyDigest, policyProfile, model, and mcpConfigVersion)                                                                                                                                                                                                              |
| `request`                             | `object`          | Request. For a workflow, originType, originRef, triggerId, scheduledAt, runStartedAt, and reworkReason; for a cycle, cron, timezone, jobName, and originKind                                                                                                                                              |
| `jobId`                               | `string \| null`  | Job ID. Can be compared with the jobId in the response of a trigger fire                                                                                                                                                                                                                                  |
| `gateFor`                             | `string \| null`  | Which failed step execution this review was created for (rs:\<number>)                                                                                                                                                                                                                                    |
| `routedFrom`                          | `string \| null`  | The step execution that decided the destination (rs:\<number>)                                                                                                                                                                                                                                            |
| `late`                                | `string \| null`  | Why a result that arrived late was not used for progress                                                                                                                                                                                                                                                  |
| `inputs`                              | `array`           | Input files (input files registered to the agent and files received from the previous step). filename and handoff (true if received from the previous step)                                                                                                                                               |
| `automation`                          | `object \| null`  | Record of the send of an external automation step. null for executions that are not external automation. Fields without a value are null                                                                                                                                                                  |
| `automation.destinationId`            | `string \| null`  | ID of the destination                                                                                                                                                                                                                                                                                     |
| `automation.destinationName`          | `string \| null`  | Name of the destination                                                                                                                                                                                                                                                                                   |
| `automation.httpStatus`               | `number \| null`  | HTTP status returned by the destination. null on a timeout or when it did not arrive                                                                                                                                                                                                                      |
| `automation.durationMs`               | `number \| null`  | Time taken by the send (milliseconds)                                                                                                                                                                                                                                                                     |
| `automation.bodyDigest`               | `string \| null`  | SHA-256 of the body that was sent (the body itself is not recorded)                                                                                                                                                                                                                                       |
| `automation.timeoutSeconds`           | `number \| null`  | How long to wait for the response (seconds)                                                                                                                                                                                                                                                               |
| `automation.visit`                    | `number \| null`  | Which visit to the step this is. A retry keeps the same value; a send-back or a resumed closed run gets a new value                                                                                                                                                                                       |
| `handoff`                             | `object \| null`  | The values and files this execution passed to the next step. null when the step has no values and file roles for the next step (outputConfig). Not shown to people who cannot see the content                                                                                                             |
| `handoff.values`                      | `object`          | Value name → the returned text (up to 1,000 characters each)                                                                                                                                                                                                                                              |
| `handoff.files`                       | `object`          | Role name → { filename } (the file name of the file with that role)                                                                                                                                                                                                                                       |
| `handoff.missing[]`                   | `object[]`        | What did not arrive: name (the value or role name) and reason ("not\_returned" (the agent did not return it) / "file\_not\_found" (not among the output files))                                                                                                                                           |
| `handoff.truncated`                   | `string[]`        | Names of values cut at 1,000 characters. \[] when none                                                                                                                                                                                                                                                    |
| `library`                             | `object`          | Project library records of the execution. Arrays inputs (versions used as input) and writes (results of writing back)                                                                                                                                                                                     |
| `library.inputs[]`                    | `object`          | fileId, filename, deleted (whether it was deleted from the project library), at, versionId, contentDigest (sha256 of the content), and workspaceName (the name in the workspace). When versionId is null, tell versions apart by contentDigest                                                            |
| `library.writes[]`                    | `object`          | The fields of inputs, plus inputVersion (the version the write-back was based on), result ("saved", "unchanged", "skipped", or "failed"), and reason (the reason for skipped or failed; for example, "not\_registered" or "invalid\_blob")                                                                |

- When `…Kind` in `questions` and `gates` is `"human"`, `…Ref` is a user ID. Otherwise, `…Ref` is null.
- `questions` includes only the questions within the newest 200 rows of the records of the execution. Read older questions in the execution timeline (rows whose `section` is `"confirmation"`).
- `files` includes up to 20 files.
- `library` covers only the oldest 200 record lines of the execution. Records of files not in the project library are not included.
  <!-- -->
- Read each tool call in the list of tool calls.

#### Response Example

```json
{
  "executionId": "rs:1842",
  "kind": "run_step",
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "stepName": "Amount check",
  "stepPosition": 2,
  "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "agentName": "Accounting Agent",
  "attempt": 1,
  "lane": "main",
  "outcome": "completed",
  "reasonCode": null,
  "resultState": "terminal",
  "terminal": true,
  "startedAt": "2026-11-18T01:30:05.000Z",
  "endedAt": "2026-11-18T01:34:40.000Z",
  "summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
  "errorMessage": null,
  "originType": "manual",
  "actorLabel": null,
  "gateDecision": null,
  "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
  "fixTarget": null,
  "platformFailure": null,
  "rerunOf": null,
  "connectionConfirmOf": null,
  "edited": null,
  "billingSteps": 3,
  "automation": null,
  "handoff": null,
  "envelope": {
    "counts": {
      "toolCalls": 14,
      "readCalls": 9,
      "mutatingSuccess": 3,
      "mutatingFailed": 0,
      "unknownCalls": 0,
      "opaqueCalls": 0,
      "workspaceWrites": 3,
      "mcpCalls": 0,
      "mcpFailed": 0
    },
    "completionReport": {
      "completed": true,
      "reasonCode": null,
      "fixTarget": null,
      "comment": "11 of 12 matched. 1 was turned into a work item because of an amount difference.",
      "truncated": false
    },
    "platformFailure": null,
    "tools": [
      "read_file",
      "write_file"
    ]
  },
  "usedSettings": {
    "manifest": null,
    "mcp": null
  },
  "questions": [],
  "gates": [],
  "artifacts": [],
  "files": [],
  "configuration": {
    "policyVersion": null,
    "policyDigest": null,
    "policyProfile": null,
    "model": null,
    "mcpConfigVersion": null
  },
  "request": {
    "originType": "manual",
    "originRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "triggerId": null,
    "scheduledAt": null,
    "runStartedAt": "2026-11-18T01:30:00.000Z",
    "reworkReason": null
  },
  "jobId": null,
  "gateFor": null,
  "routedFrom": null,
  "late": null,
  "inputs": [
    {
      "filename": "invoice.json",
      "handoff": false
    }
  ],
  "library": {
    "inputs": [],
    "writes": []
  }
}
```

#### Error Responses

| Status | code                  | Description                                                                                      |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`   | projectId is not a UUID, or executionId is neither rs:\<number> nor a UUID                       |
| `403`  | `insufficient_scope`  | The project:read scope is missing                                                                |
| `403`  | `forbidden`           | Called with a system integration token                                                           |
| `403`  | `sso_required`        | The user does not sign in with SSO                                                               |
| `404`  | `execution_not_found` | The execution does not exist, belongs to another project, or you are not a member of the project |

### GET`/v1/projects/{projectId}/executions/{executionId}/operations`

Gets the list of tool calls in an execution, page by page from the newest records to older ones. Within a page, `operations` are in oldest-first order. Reading to the end gives all the calls of the execution. Arguments and responses are not included.

#### Query Parameters

| Parameter | Type     | Default | Description                                                            |
| --------- | -------- | ------- | ---------------------------------------------------------------------- |
| `cursor`  | `string` | `—`     | Cursor for the next page (the cursor value from the previous response) |

The number of items per page is not fixed, so there is no `limit`.

#### Request Example

**List execution operations**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                         | Type             | Description                                                                                                                        |
| ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `operations`                  | `array`          | Array of calls                                                                                                                     |
| `operations[].operationId`    | `string \| null` | Call ID                                                                                                                            |
| `operations[].kind`           | `string \| null` | Kind of the row. "tool" (a tool call) / "a2a" (a call to an A2A agent) / "access" (the check before reading a file)                |
| `operations[].resource`       | `string \| null` | Tool (mcp:\<server name>:\<tool name> for MCP)                                                                                     |
| `operations[].action`         | `string \| null` | Operation                                                                                                                          |
| `operations[].path`           | `string \| null` | Path of the file read                                                                                                              |
| `operations[].mcpServer`      | `string \| null` | Name of the MCP server                                                                                                             |
| `operations[].connectionId`   | `string \| null` | Connector ID (connectionId of the connector API)                                                                                   |
| `operations[].connectionKind` | `string \| null` | Kind of connector ("mcp" or "a2a")                                                                                                 |
| `operations[].attempted`      | `boolean`        | Whether the call was made                                                                                                          |
| `operations[].effect`         | `string \| null` | Result of the call. "ok" (succeeded) / "error" (a tool error) / "failed" (failed). null while the result has not been recorded yet |
| `operations[].denied`         | `string \| null` | Reason when it was stopped                                                                                                         |
| `operations[].durationMs`     | `number \| null` | Time taken (milliseconds)                                                                                                          |
| `operations[].reason`         | `string \| null` | Reason of the check (only rows whose kind is "access"; for example, "granted" or "path\_not\_found"). null for other rows          |
| `hasMore`                     | `boolean`        | Whether there are more                                                                                                             |
| `cursor`                      | `string`         | Cursor for the next page. Included only when hasMore is true                                                                       |

When the records of one call are split across a page boundary, rows with the same `operationId` appear on both pages. Treat rows with the same `operationId` as one call.

#### Response Example

```json
{
  "operations": [
    {
      "operationId": "call:toolu_01ABC",
      "kind": "access",
      "resource": "read_file",
      "action": "read",
      "path": "/workspace/invoice.json",
      "mcpServer": null,
      "connectionId": null,
      "connectionKind": null,
      "attempted": true,
      "effect": null,
      "denied": null,
      "durationMs": 12,
      "reason": "granted"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                  | Description                                                                                      |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`   | projectId or executionId has the wrong form, or cursor is invalid                                |
| `400`  | `invalid_cursor`      | cursor cannot be read                                                                            |
| `403`  | `insufficient_scope`  | The project:read scope is missing                                                                |
| `403`  | `forbidden`           | Called with a system integration token                                                           |
| `403`  | `sso_required`        | The user does not sign in with SSO                                                               |
| `404`  | `execution_not_found` | The execution does not exist, belongs to another project, or you are not a member of the project |

### GET`/v1/projects/{projectId}/executions/{executionId}/timeline`

Gets the timeline of an execution (the records of the execution). The records of the request, evidence, actions, confirmations, and result are listed from oldest.

#### Query Parameters

| Parameter | Type      | Default | Description                                                            |
| --------- | --------- | ------- | ---------------------------------------------------------------------- |
| `limit`   | `integer` | `50`    | Number of rows per page (1-100)                                        |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response) |

#### Request Example

**Get execution timeline**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline?limit=50" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "50"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline" + "?limit=50",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline?limit=50", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                        | Type             | Description                                                                                                                                                         |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rootExecutionId`            | `string`         | Execution ID                                                                                                                                                        |
| `origin`                     | `string \| null` | How the execution started. "job" (job) / "chat" (chat)                                                                                                              |
| `owner`                      | `object`         | The owner of the execution                                                                                                                                          |
| `owner.userId`               | `string \| null` | User ID of the owner. null when unknown                                                                                                                             |
| `executions`                 | `object`         | Summaries of the execution (items): result, settings, numbers of tool calls, and so on                                                                              |
| `timeline`                   | `object`         | Record rows (items)                                                                                                                                                 |
| `timeline.items[].at`        | `string`         | Time of the record                                                                                                                                                  |
| `timeline.items[].key`       | `number`         | ID of the record. A "tool.access" row corresponds to the operationId of the tool-call list (`call:<call ID>` for rows with a call ID, `row:<key>` for rows without) |
| `timeline.items[].section`   | `string`         | "request", "evidence", "action", "confirmation", "result", or "other"                                                                                               |
| `timeline.items[].eventType` | `string`         | Kind of record (for example, "context.manifest", "runtime.mcp.connected", "tool.invoked", or "guardrail.blocked")                                                   |
| `timeline.items[].meta`      | `object`         | Contents of each record. Field names are returned as recorded                                                                                                       |
| `deleted`                    | `object`         | Deleted conversations and resources                                                                                                                                 |
| `deleted.conversations`      | `string[]`       | IDs of deleted conversations                                                                                                                                        |
| `deleted.resources`          | `string[]`       | Deleted resources (such as files). Only those that appear in `timeline.items[].resource` on this page                                                               |
| `hasMore`                    | `boolean`        | Whether there are more                                                                                                                                              |
| `cursor`                     | `string`         | Cursor for the next page. Included only when hasMore is true                                                                                                        |
| `snapshotAt`                 | `string \| null` | When the records were read                                                                                                                                          |

`timeline.items[]` also has `writer`, `actor`, `resource`, `action`, `decision`, `reason`, `policyVersion`, `ref`, and `available`. The contents of `meta` differ by record type, and field names are returned as recorded (snake\_case). One page is up to 64 KiB.

#### Response Example

```json
{
  "rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
  "origin": "job",
  "owner": {
    "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "executions": {
    "items": [
      {
        "executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
        "origin": "job",
        "rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
        "job": {
          "id": "e3a5c7d9-1b2f-4c6e-8a0b-3d5f7a9c1e2b",
          "mode": "once",
          "scheduleType": "once",
          "deletedAt": null,
          "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
          "projectStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "projectAgentId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
          "projectRunId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13"
        },
        "ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
        "messageId": "b2c4d6e8-0a1b-4c3d-9e5f-7a9b1c3d5e7f",
        "stepIndex": 0,
        "status": "completed",
        "startedAt": "2026-11-18T01:30:05.000Z",
        "completedAt": "2026-11-18T01:34:40.000Z",
        "terminal": {
          "state": "terminal",
          "outcome": "completed",
          "outcomeReasonCode": null,
          "hadMutatingSuccess": true,
          "terminalAt": "2026-11-18T01:34:40.000Z",
          "degradedFrom": null,
          "envelopeVersion": 1,
          "envelopeAppliedAt": "2026-11-18T01:34:41.000Z"
        },
        "logical": {
          "outcome": "completed",
          "hadMutatingSuccess": true,
          "terminalAt": "2026-11-18T01:34:40.000Z"
        },
        "configuration": {
          "policyVersion": null,
          "policyDigest": null,
          "policyProfile": null,
          "model": null,
          "mcpConfigVersion": null
        },
        "runtime": {
          "podAdoptedAt": null,
          "suspendedAt": null,
          "interruptedReason": null
        },
        "alertDelivery": {
          "status": null,
          "errorPresent": false,
          "at": null
        },
        "envelope": {
          "envelopeVersion": 1,
          "outcome": "completed",
          "hadMutatingSuccess": true,
          "counts": {
            "toolCalls": 14,
            "mutatingSuccess": 3
          },
          "completionReport": {
            "completed": true,
            "reasonCode": null,
            "fixTarget": null,
            "hasComment": true,
            "truncated": false
          }
        },
        "occurrence": null,
        "projectRun": {
          "id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
          "originType": "manual",
          "status": "running",
          "currentStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
          "snapshotSchemaVersion": 3
        },
        "runStep": {
          "id": "1842",
          "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
          "attempt": 1,
          "status": "done",
          "laneId": null,
          "resumeCommandId": null,
          "supersededBy": null
        },
        "startActor": {
          "kind": "person",
          "ref": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        "missing": []
      }
    ]
  },
  "timeline": {
    "items": [
      {
        "at": "2026-11-18T01:30:06.000Z",
        "key": 1201,
        "section": "evidence",
        "eventType": "context.manifest",
        "writer": "worker",
        "actor": {
          "kind": "agent",
          "ref": null,
          "onBehalfOf": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
        },
        "resource": null,
        "action": null,
        "decision": null,
        "reason": null,
        "policyVersion": null,
        "ref": {
          "executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
          "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
          "messageId": null,
          "requestId": null,
          "sourceEventId": null,
          "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
          "rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
          "payloadDigest": null
        },
        "meta": {},
        "available": true
      }
    ]
  },
  "deleted": {
    "conversations": [],
    "resources": []
  },
  "hasMore": false,
  "snapshotAt": "2026-11-18T05:40:00.000Z"
}
```

#### Error Responses

| Status | code                  | Description                                                                                                  |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`   | projectId or executionId has the wrong form, limit is not an integer between 1 and 100, or cursor is invalid |
| `400`  | `invalid_cursor`      | cursor cannot be read                                                                                        |
| `403`  | `insufficient_scope`  | The project:read scope is missing                                                                            |
| `403`  | `forbidden`           | Called with a system integration token                                                                       |
| `403`  | `sso_required`        | The user does not sign in with SSO                                                                           |
| `404`  | `execution_not_found` | The execution does not exist, belongs to another project, or you are not a member of the project             |
| `413`  | `trace_too_large`     | The records are too large to read                                                                            |
| `502`  | `trace_unreachable`   | The records could not be read (try again later)                                                              |
| `503`  | `trace_unavailable`   | Reading the records is not available                                                                         |

### POST`/v1/projects/{projectId}/executions/{executionId}/rerun`

For a cycle project, runs a failed sweep execution again with the same placement and the same step. This is the same as rerunning on the screen. Owners and operators (including people with the organization operations role) can call this API. No body is needed (a body is not used even if sent).

- When a periodic sweep ends with `outcome` `"failed"` or `"timeout"`, the platform retries it once soon after as a new execution (`attempt` 2). Before you send a rerun, check the later executions of the same placement and step. If the retry fails too, the retry execution appears in the [queue](#queue) as `sweep_failed`.
- When accepted, the failure is removed from the [queue](#queue).
- The new execution appears in the execution history when it starts. Look for the execution whose `rerunOf` is the ID of the original execution.
- Sending the same execution again after it has been accepted returns `409 Conflict` (`already_requested`). After this execution has been relaunched because a connection confirmation was approved, sending the same execution also returns `409 Conflict` (`already_requested`), because the relaunch was accepted as a rerun of this execution. The relaunched new execution can be rerun if it fails.
- If a rerun of this execution has been accepted before the connection confirmation is decided, approving it does not relaunch the Agent.

#### Path Parameters

| パラメータ         | 型        | 必須 | 説明                                                                                 |
| ------------- | -------- | -- | ---------------------------------------------------------------------------------- |
| `projectId`   | `string` | 必須 | Project ID (UUID)                                                                  |
| `executionId` | `string` | 必須 | ID of the sweep execution (UUID). Executions of workflow steps cannot be specified |

#### Request Example

**Rerun execution**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/rerun \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/rerun",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/rerun",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/rerun", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (202 Accepted)

| Field            | Type      | Description                  |
| ---------------- | --------- | ---------------------------- |
| `executionId`    | `string`  | ID of the original execution |
| `rerunRequested` | `boolean` | true when accepted           |

#### Response Example

```json
{
  "executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "rerunRequested": true
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                    |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId is not a UUID, executionId is neither rs:\<number> nor a UUID, or executionId is an execution of a workflow step                                                                                     |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                |
| `403`  | `insufficient_scope`     | The project:run scope is missing                                                                                                                                                                               |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                         |
| `403`  | `operator_only`          | A member who is neither an owner nor an operator and does not have the organization operations role                                                                                                            |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                             |
| `404`  | `execution_not_found`    | The execution does not exist, belongs to another project, its placement no longer handles that step (for example, the placement was removed or its steps were changed), or you are not a member of the project |
| `409`  | `not_failed`             | The execution did not end in failure (incomplete, failed, denied, or timeout)                                                                                                                                  |
| `409`  | `already_requested`      | A rerun of this execution has already been accepted (including when this execution was relaunched because a connection confirmation was approved)                                                              |
| `409`  | `principal`              | The principal that runs the project (the current owner of the project) cannot be confirmed                                                                                                                     |
| `409`  | `relink_required`        | References missing after import must be reconnected before the project can run or resume. For how to fix it, see relink\_required in the error table of starting a workflow run                                |
| `409`  | `admin_stopped`          | An administrator has stopped the project, or the Agent of the placement to rerun. Ask an administrator to resume it                                                                                            |
| `409`  | `step_disabled`          | The step of this placement is disabled, so it does not run. Ask a project owner to enable the step (PATCH /v1/projects/{projectId}/steps/{stepId} with enabled true) before running this placement again       |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                        |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                           |

## Files

Gets the content of files found in a project (`files[]` in execution results, `evidence.files[]` in review request evidence<!-- -->, and files in the [project library](#library)). In each case, pass the `filepath` from the response to `path` as is.

### Endpoint List

| メソッド | エンドポイント                                  | 説明                        | Scope (SaaS)             |
| ---- | ---------------------------------------- | ------------------------- | ------------------------ |
| GET  | `/v1/projects/{projectId}/files/content` | Get the content of a file | `project:read / mcp:all` |

### GET`/v1/projects/{projectId}/files/content`

Gets the content of a file. Only project members can read it (even for a shared project, a non-member gets 404; a person with the organization operations role who does not take part in the project gets `400 Bad Request` (`file_not_found`)). It can also be called with `HEAD`. The same headers are returned without the body, so you can check the size first. <!-- -->It can also be called with an MCP token (`mcp:all`)<!-- -->, so a file URL returned by an MCP tool can be fetched with the same token.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Query Parameters

| Parameter    | Type     | Default | Description                                                                                                                                            |
| ------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`       | `string` | `—`     | Required. The file path (files\[].filepath in an execution result, evidence.files\[].filepath in a review request, or filepath in the project library) |
| `version_id` | `string` | `—`     | ID of a version. The current version if omitted. For a file in the project library, versionId in the version list                                      |

For files in execution results, the readable versions are the current version and the versions written after the execution in which the project first recorded the file started.<!-- --> For files in the project library, all versions can be read.

#### Request Example

**Get project file content**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content",
  headers={"Authorization": f"Bearer {token}"},
  params={"path": "/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf"},
)

with open("report.pdf", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content" + "?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const bytes = new Uint8Array(await response.arrayBuffer());
console.log(bytes.length);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
os.WriteFile("report.pdf", body, 0644)
```

#### Response (200 OK)

The content of the file is returned as is.

| Response Header           | Description                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`            | MIME type of the file                                                                                                |
| `Content-Length`          | File size in bytes. Present only when the size is known                                                              |
| `Accept-Ranges`           | "bytes" (present only when the size is known)                                                                        |
| `X-Content-Type-Options`  | "nosniff"                                                                                                            |
| `Content-Disposition`     | "attachment" for HTML, SVG, and XML files (returned as a download)                                                   |
| `Content-Security-Policy` | For HTML, SVG, and XML files, a policy that blocks script execution and external loading (sandbox and others) is set |

#### Error Responses

| Status | code                 | Description                                                                |
| ------ | -------------------- | -------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID, or path is missing                                |
| `400`  | `file_not_found`     | The file specified by path cannot be read                                  |
| `400`  | `version_not_found`  | The version specified by version\_id does not exist (the file can be read) |
| `403`  | `insufficient_scope` | The project:read scope is missing                                          |
| `403`  | `forbidden`          | Called with a system integration token                                     |
| `403`  | `sso_required`       | The user does not sign in with SSO                                         |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                        |

Storage failures (500, 502, and 503) are the same as [Artifact Retrieval](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#artifacts) (`GET /v1/files/proxy`).

## Library

Handles the files shared by the members of a project (the project library). Files bound to a step of a placement are passed to the workspace when that step runs, and a write-back by the execution makes a new version. This is separate from your own files on the conversation side (the [file library](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#library)).

- Members of the project can list files, list versions, register, copy in, add a new version, restore a previous version, and copy in the newer version of the source output. Only owners can delete files and bind files to placements (a member gets `403 Forbidden` (`owner_only`)). A person with the organization operations role who does not take part in the project gets `409 Conflict` (`forbidden_role`) for all of them.
- Deleting also uses the `project:write` scope (not `project:delete`).
- Get the content with [Get the content of a file](#get-project-file-content) (`GET /v1/projects/{projectId}/files/content`) by passing `filepath` as `path`. For a previous version, pass `versionId` from the version list as `version_id`.
- Keys that identify resends are not accepted. A file with the same name cannot be registered or copied in (`409 Conflict` (`name_taken`)), so resending does not create two files. An execution output can be copied in as a new version of the file with the same name by sending `fileId` (only an output of the same type (extension) as that file; see [Add a new version](#add-project-library-version) for which extensions count as the same).

### Endpoint List

| メソッド   | エンドポイント                                                              | 説明                                             | Scope (SaaS)    |
| ------ | -------------------------------------------------------------------- | ---------------------------------------------- | --------------- |
| GET    | `/v1/projects/{projectId}/library`                                   | List files                                     | `project:read`  |
| GET    | `/v1/projects/{projectId}/library/{fileId}/versions`                 | List the versions of a file                    | `project:read`  |
| POST   | `/v1/projects/{projectId}/library`                                   | Register a file                                | `project:write` |
| POST   | `/v1/projects/{projectId}/library/copy`                              | Copy in a file                                 | `project:write` |
| PUT    | `/v1/projects/{projectId}/library/{fileId}/content`                  | Add a new version                              | `project:write` |
| POST   | `/v1/projects/{projectId}/library/{fileId}/restore`                  | Restore a previous version                     | `project:write` |
| POST   | `/v1/projects/{projectId}/library/{fileId}/import-latest`            | Copy in the newer version of the source output | `project:write` |
| DELETE | `/v1/projects/{projectId}/library/{fileId}`                          | Delete a file                                  | `project:write` |
| PUT    | `/v1/projects/{projectId}/placements/{placementId}/library-bindings` | Bind files to a step of a placement            | `project:write` |

### File Fields

The fields of an item in the list and of the responses of register, copy in, add a new version, restore, and copy in the newer version of the source output.

| Field              | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fileId`           | `string`         | ID of the file (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `filename`         | `string \| null` | Name of the file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `filepath`         | `string`         | Path of the file. Can be passed as is to path of Get the content of a file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `source`           | `string`         | "user" (registered or copied in by a person) or "agent" (copied in from an execution output)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `sourceFile`       | `object \| null` | For a file copied in from an execution output, that output: executionId is the ID of the execution (null when unknown) and filepath is the path of the output. When another execution's output is later copied in with Copy in (POST /v1/projects/{projectId}/library/copy with fileId), it becomes that execution. Copying in the newer version of the source output (import-latest) does not change it (the content becomes the newest output found, and executionId and filepath stay). null for a file not copied in from an execution output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sourceFiles`      | `object[]`       | The records of execution outputs put into this file (executionId and filepath), oldest first. Copy in (POST /v1/projects/{projectId}/library/copy) and the screen's "save with this name every time" are included. For a file created from an execution output, the pair it was created from always stays and later records are kept up to the newest 50 (up to 51 in all). For a file created otherwise (for example uploaded), the newest 50 records are kept. Older records are dropped. Copy-ins that added no version because the content was the same are included. Copying in the newer version of the source output (import-latest) is not included. Use it to tell whether an execution output was already copied into this file with Copy in. Usually the last item is the same as sourceFile. \[] when none                                                                                                                                                                                                                           |
| `newerVersionAt`   | `string \| null` | When the source output (for a file copied in from a sweep's output, also the output with the same filepath of a later run; see below) has a version more than one minute newer than the latest version of this file, the time of that version (ISO 8601). null when there is none, for a file bound to a step of a placement (the execution writes it back), or when none of the checked outputs can be read. For a file copied in from a sweep's output, the source output and the outputs at the same filepath in the five latest sweep workspaces of its placement and step are checked, and the time of the newest one is returned (a sweep that runs on its schedule keeps one workspace; a sweep started by a webhook or email, and a rerun of a sweep, get a new one each time). For a file copied in from a workflow step's output, only the source output is checked. Set only in the list; null in write responses. When the source output is written again with the same content, copying it in adds no version and the value remains |
| `mimeType`         | `string?`        | MIME type. Not included when unknown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `size`             | `number?`        | File size (bytes). Not included when unknown                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `currentVersionId` | `string \| null` | ID of the current version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `digest`           | `string`         | The value to send as baseDigest to add a new version, restore a previous version, copy in with fileId, or copy in the newer version of the source output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `createdAt`        | `string \| null` | Creation time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `updatedAt`        | `string \| null` | Last update time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### GET`/v1/projects/{projectId}/library`

Gets the files of the project library in order of last update time. Supports cursor-based pagination.

#### Query Parameters

| Parameter | Type      | Default  | Description                                                            |
| --------- | --------- | -------- | ---------------------------------------------------------------------- |
| `source`  | `string`  | `—`      | Filter by "user" or "agent"                                            |
| `order`   | `string`  | `"desc"` | "asc" (oldest first) or "desc" (newest first)                          |
| `limit`   | `integer` | `50`     | Number of items per page (1-100)                                       |
| `cursor`  | `string`  | `—`      | Cursor for the next page (the cursor value from the previous response) |

#### Request Example

**List project library files**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library?source=user&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library",
  headers={"Authorization": f"Bearer {token}"},
  params={"source": "user", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library" + "?source=user&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library?source=user&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field     | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `files`   | `array`   | Array of files. The fields of an item are in "File Fields" above |
| `hasMore` | `boolean` | Whether there is a next page                                     |
| `cursor`  | `string`  | Cursor for the next page. Included only when hasMore is true     |

#### Response Example

```json
{
  "files": [
    {
      "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "filename": "rules.xlsx",
      "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "source": "user",
      "sourceFile": null,
      "sourceFiles": [],
      "newerVersionAt": null,
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 20480,
      "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
      "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
      "createdAt": "2026-11-10T01:00:00.000Z",
      "updatedAt": "2026-11-10T01:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                            |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId is not a UUID, source or order is not one of the values above, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                      |
| `403`  | `forbidden`          | Called with a system integration token                                                                 |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                     |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                    |

### GET`/v1/projects/{projectId}/library/{fileId}/versions`

Gets the versions of a file, newest first. Up to the latest 50 versions are returned, and `hasMore` is always `false` (older versions are not returned even if they exist).

#### Request Example

**List project library file versions**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/versions", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                      | Type             | Description                                                                                                                                              |
| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fileId`                   | `string`         | ID of the file                                                                                                                                           |
| `currentVersionId`         | `string \| null` | ID of the current version                                                                                                                                |
| `digest`                   | `string`         | The value to send as baseDigest to add a new version, restore a previous version, copy in with fileId, or copy in the newer version of the source output |
| `versions`                 | `array`          | Array of versions (newest first)                                                                                                                         |
| `versions[].versionId`     | `string \| null` | ID of the version. Pass it as version\_id of Get the content of a file, or as versionId of Restore a previous version                                    |
| `versions[].size`          | `number \| null` | Size (bytes)                                                                                                                                             |
| `versions[].createdAt`     | `string \| null` | When the version was made (ISO 8601)                                                                                                                     |
| `versions[].isCurrent`     | `boolean`        | Whether it is the current version                                                                                                                        |
| `versions[].source`        | `string \| null` | "register" (registered or a new version), "restore" (restored from a previous version), or "writeback" (written back by an execution)                    |
| `versions[].contentDigest` | `string \| null` | sha256 of the content                                                                                                                                    |
| `versions[].createdByKind` | `string \| null` | Kind of what wrote the version ("human" or "system")                                                                                                     |
| `versions[].createdByRef`  | `string \| null` | What wrote the version. A user ID for a person, or execution:\<execution ID> for a write-back by an execution                                            |
| `versions[].executionId`   | `string \| null` | ID of the execution that wrote it back (only for a write-back)                                                                                           |
| `hasMore`                  | `boolean`        | Always false                                                                                                                                             |

When the records of the versions cannot be read, `source`, `contentDigest`, `createdByKind`, and `createdByRef` are null.

#### Response Example

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "versions": [
    {
      "versionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
      "size": 20480,
      "createdAt": "2026-11-10T01:00:00.000Z",
      "isCurrent": true,
      "source": "register",
      "contentDigest": "50189489124ca87fb0d37b288ca9b589e71a018109f2975abc6e24ce1a2ee228",
      "createdByKind": "human",
      "createdByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "executionId": null
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                    |
| ------ | -------------------- | ------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or fileId is not a UUID                                              |
| `403`  | `insufficient_scope` | The project:read scope is missing                                              |
| `403`  | `forbidden`          | Called with a system integration token                                         |
| `403`  | `sso_required`       | The user does not sign in with SSO                                             |
| `404`  | `file_not_found`     | The file does not exist or was deleted, or you are not a member of the project |

### POST`/v1/projects/{projectId}/library`

Registers one file. Send the request as `multipart/form-data`. The file name becomes the name in the library as is. The file type (`mimeType`) is determined from the file name's extension (the `Content-Type` of the part you send is not used; if the extension does not tell, it is `application/octet-stream`).

#### Request Body (multipart/form-data)

| Field   | Type   | Required | Description                                                                                                                                                                             |
| ------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `files` | `file` | Yes      | The file to register (only one; up to 512 MB). The file name can be up to 255 characters, not counting leading and trailing whitespace, and cannot contain /, \\, or control characters |

- If you did not receive a response (for example, `504 Gateway Timeout` (`upstream_timeout`)), the file may have been registered. Check the list before resending.
- It is kept in the records (audit trail).

#### Request Example

**Register project library file**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library \
-H "Authorization: Bearer <access_token>" \
-F "files=@rules.xlsx"
```

**Python**

```python
import requests

with open("rules.xlsx", "rb") as f:
  response = requests.post(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={},
  )

print(response.json())
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("files", file); // File object

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

const data = await response.json();
console.log(data);
```

**Go**

```go
file, _ := os.Open("rules.xlsx")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "rules.xlsx")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (201 Created)

Returns the registered file ("File Fields" above).

#### Response Example

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-10T01:00:00.000Z"
}
```

#### Error Responses

| Status | code                              | Description                                                                                                         |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId is not a UUID, or files is missing, has two or more files, or a file was sent in a field other than files |
| `400`  | `invalid_filename`                | The file name is empty, exceeds 255 characters, or contains a character that cannot be used                         |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                  |
| `403`  | `forbidden`                       | Called with a system integration token                                                                              |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                  |
| `403`  | `feature_not_permitted`           | An administrator has not permitted file uploads                                                                     |
| `404`  | `project_not_found`               | The project does not exist, or you are not a member                                                                 |
| `409`  | `name_taken`                      | A file with the same name is in the project library                                                                 |
| `413`  | `file_too_large`                  | The file exceeds 512 MB                                                                                             |
| `415`  | `unsupported_media_type`          | The Content-Type is not multipart/form-data                                                                         |
| `503`  | `feature_permissions_unavailable` | Feature permissions could not be checked (wait and retry)                                                           |

### POST`/v1/projects/{projectId}/library/copy`

Copies a file from your own file library, or an output of an execution of this project, into the project library. One file per call. A file in your file library is copied as its content at that time, and an execution output as the version at the end of that execution's record. Changing the original file later does not change the copied file.

#### Request Body

| Field         | Type     | Required | Description                                                                                                                                                                                                                  |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filepath`    | `string` | Yes      | Path of the file to copy in: filepath from GET /v1/library for a file in your file library, or files\[].filepath of the execution result for an execution output (up to 1024 characters)                                     |
| `executionId` | `string` | —        | ID of the execution when copying in an execution output (rs:\<number> or a UUID). If omitted, a file in your file library is copied in                                                                                       |
| `fileId`      | `string` | —        | When copying in an execution output as a new version of an existing file in the project library, the fileId (UUID) of that file. Can be sent only with executionId. Only an output of the same type (extension) as that file |
| `baseDigest`  | `string` | —        | Required when sending fileId. The digest of that file (the value from the list, the version list, or a write response)                                                                                                       |

- With `fileId`, a new version is added to that file (it does not become `name_taken`). If the extension of the name of the output to copy in differs from the extension of the name of that file, the request is rejected (`409 Conflict` (`type_mismatch`); see [Add a new version](#add-project-library-version) for which extensions count as the same). If the content is the same as the current version, no version is added.

It is kept in the records (audit trail) (with `fileId`, only when a version is added).

#### Request Example

**Copy file into project library**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy",
  headers={"Authorization": f"Bearer {token}"},
  json={'filepath': '/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/copy", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (201 Created / 200 OK)

Returns the copied file ("File Fields" above). Without `fileId` it is `201 Created`; with `fileId` it is `200 OK`.

#### Response Example

```json
{
  "fileId": "4a6c8e0f-2b3d-4e5f-9a1b-7c8d9e0f1a2b",
  "filename": "report.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/4a6c8e0f-2b3d-4e5f-9a1b-7c8d9e0f1a2b",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "digest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-10T01:00:00.000Z"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                                                        |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`      | projectId is not a UUID, filepath is missing, empty, or exceeds 1024 characters, executionId is neither rs:\<number> nor a UUID, fileId is not a UUID, fileId was sent without executionId, or fileId was sent while baseDigest is missing, empty, or not a string |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                    |
| `400`  | `file_not_found`         | The file of filepath does not exist, is not yours, or is not an output of that execution                                                                                                                                                                           |
| `400`  | `execution_not_found`    | The execution of executionId does not exist, or belongs to another project                                                                                                                                                                                         |
| `400`  | `invalid_filename`       | The name of the file cannot be used                                                                                                                                                                                                                                |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                                                                                                                                                 |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                                             |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                                                 |
| `404`  | `project_not_found`      | The project does not exist, or you are not a member                                                                                                                                                                                                                |
| `404`  | `file_not_found`         | The file of fileId does not exist or has been deleted                                                                                                                                                                                                              |
| `409`  | `name_taken`             | A file with the same name is in the project library (for an execution output, sending the fileId and baseDigest of that file copies it in as a new version)                                                                                                        |
| `409`  | `stale_base`             | The version of the file of fileId has changed since you got it                                                                                                                                                                                                     |
| `409`  | `overwritten`            | The version at the time of that execution's record was overwritten by a later execution and no longer exists (copy it from the output of a later execution that wrote it)                                                                                          |
| `409`  | `type_mismatch`          | With fileId, the extension of the name of the output to copy in differs from the extension of the name of that file (choose an execution output with the same extension, or omit fileId and baseDigest to copy it in as a new file)                                |
| `413`  | `file_too_large`         | The file to copy in exceeds 512 MB                                                                                                                                                                                                                                 |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                                                            |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                                                               |

### PUT`/v1/projects/{projectId}/library/{fileId}/content`

Adds a new version to a file. Send the request as `multipart/form-data`. Previous versions are kept. The file type (`mimeType`) is determined from the extension of the name in the library (the `Content-Type` of the file you send is not used). If the extension of the name of the file you send differs from the extension of the name in the library, the request is rejected (`409 Conflict` (`type_mismatch`); case is ignored, and `jpg` and `jpeg`, `htm` and `html`, `tif` and `tiff`, and `yml` and `yaml` are treated as the same type). The name in the library does not change.

#### Request Body (multipart/form-data)

| Field        | Type     | Required | Description                                                                           |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------- |
| `baseDigest` | `string` | Yes      | The digest of the file (the value in the list, the version list, or a write response) |
| `files`      | `file`   | Yes      | The content of the new version (only one; up to 512 MB)                               |

- If the content is the same as the current version, no version is added (`currentVersionId` and `digest` do not change).
- Resending returns `409 Conflict` (`stale_base`) because the first request changed the version. Check with the version list.
- It is kept in the records (audit trail) only when a version is added.

#### Request Example

**Add library file version**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content \
-H "Authorization: Bearer <access_token>" \
-F "files=@rules.xlsx" \
-F "baseDigest=WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"
```

**Python**

```python
import requests

with open("rules.xlsx", "rb") as f:
  response = requests.put(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={"baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"},
  )

print(response.json())
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("files", file); // File object
formData.append("baseDigest", "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0");

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content", {
method: "PUT",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

const data = await response.json();
console.log(data);
```

**Go**

```go
file, _ := os.Open("rules.xlsx")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "rules.xlsx")
io.Copy(part, file)
writer.WriteField("baseDigest", "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0")
writer.Close()

req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/content", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

Returns the file after adding the version ("File Fields" above).

#### Response Example

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
  "digest": "WyJjNGQ5ZTJmMS0wYTNiLTRjNmQtOGU3Zi01YTFiMmMzZDRlNmYiLCIzYjZkYzMyNDY3NWE3YTQxZmExYjFjMzliNmIyYTY3ZGY4NDI0MTRkZTY1ZDg5MzdlOTUyMzM1NDRkNTg3ODJiIl0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-12T02:00:00.000Z"
}
```

#### Error Responses

| Status | code                              | Description                                                                                                                                                                  |
| ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`               | projectId or fileId is not a UUID, baseDigest is missing, empty, or not a string, or files is missing, has two or more files, or a file was sent in a field other than files |
| `403`  | `insufficient_scope`              | The project:write scope is missing                                                                                                                                           |
| `403`  | `forbidden`                       | Called with a system integration token                                                                                                                                       |
| `403`  | `sso_required`                    | The user does not sign in with SSO                                                                                                                                           |
| `403`  | `feature_not_permitted`           | An administrator has not permitted file uploads                                                                                                                              |
| `404`  | `file_not_found`                  | The file does not exist or was deleted, or you are not a member of the project                                                                                               |
| `409`  | `stale_base`                      | The version of the file changed after you got it                                                                                                                             |
| `409`  | `type_mismatch`                   | The extension of the name of the file you sent differs from the extension of the name in the library (send a file with the same extension, or register it as a new file)     |
| `413`  | `file_too_large`                  | The file exceeds 512 MB                                                                                                                                                      |
| `415`  | `unsupported_media_type`          | The Content-Type is not multipart/form-data                                                                                                                                  |
| `503`  | `feature_permissions_unavailable` | Feature permissions could not be checked (wait and retry)                                                                                                                    |

### POST`/v1/projects/{projectId}/library/{fileId}/restore`

Makes a new version with the content of a previous version. Previous versions are kept.

#### Request Body

| Field        | Type     | Required | Description                                                  |
| ------------ | -------- | -------- | ------------------------------------------------------------ |
| `versionId`  | `string` | Yes      | ID of the version to restore (versionId in the version list) |
| `baseDigest` | `string` | Yes      | The digest of the file                                       |

That no version is added when the content is the same as the current version, resending, and the records (audit trail) are the same as Add a new version.

#### Request Example

**Restore library file version**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
  "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore",
  headers={"Authorization": f"Bearer {token}"},
  json={'versionId': 'c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f', 'baseDigest': 'WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f", "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f", "baseDigest": "WyIzYjhhMWM1ZS03ZDJmLTRlOWEtYTZjMC0xZjRkOGIyZTVhNzkiLCI1MDE4OTQ4OTEyNGNhODdmYjBkMzdiMjg4Y2E5YjU4OWU3MWEwMTgxMDlmMjk3NWFiYzZlMjRjZTFhMmVlMjI4Il0"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6/restore", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

Returns the file after restoring ("File Fields" above).

#### Response Example

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "source": "user",
  "sourceFile": null,
  "sourceFiles": [],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "7a9c1e3f-5b2d-4f6a-8c0e-2d4f6a8c0e1b",
  "digest": "WyI3YTljMWUzZi01YjJkLTRmNmEtOGMwZS0yZDRmNmE4YzBlMWIiLCI0NmE3NTkxOTNmOTYxZjA2ODY2NDY0ZjA2MmFjYTZkYWZhOGM1ZDg4MTA4MjkxZDUyYmUwZjFmNjRiNzc5MjliIl0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-13T03:00:00.000Z"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                       |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or fileId is not a UUID, versionId is missing, empty, or not a string, or baseDigest is missing, empty, or not a string |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                   |
| `400`  | `version_not_found`      | The version of versionId does not exist                                                                                           |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                |
| `403`  | `forbidden`              | Called with a system integration token                                                                                            |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                |
| `404`  | `file_not_found`         | The file does not exist or was deleted, or you are not a member of the project                                                    |
| `409`  | `stale_base`             | The version of the file changed after you got it                                                                                  |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                           |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                              |

### POST`/v1/projects/{projectId}/library/{fileId}/import-latest`

For a file copied in from an execution output, adds the newest output found in the same way as newerVersionAt in the list (for a sweep's output, this can be the output at the same filepath in another workspace of a later run) as a new version. Use it when newerVersionAt in the list is set. When the content is the same as the current version, no version is added and newerVersionAt also remains (whether it is newer is decided by time, not by content; when currentVersionId does not change, the content is the same). It cannot be used for a file bound to a step of a placement (the execution writes it back). It is kept in the records (audit trail), only when a version is added.

#### Request Body

| Field        | Type     | Required | Description            |
| ------------ | -------- | -------- | ---------------------- |
| `baseDigest` | `string` | Yes      | The digest of the file |

#### Request Example

**Import latest source version**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "WyIyYzRlNmE4Yi0wZDFmLTRiM2MtOWE1ZS03ZjliMWQzZjVhN2MiLCIwOGJmNTQ1NmFiYmYwZGYxZTE5ZmJhMTYwYzk2NTAwNTgzOWQyYWE2M2YzYThkYjA0M2FjNzgzOThjMGQ0NTE4Il0"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e/import-latest", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

Returns the file after copying in ("File Fields" above).

#### Response Example

```json
{
  "fileId": "b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
  "filename": "rules.xlsx",
  "filepath": "/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/b5c6d7e8-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
  "source": "agent",
  "sourceFile": {
    "executionId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "filepath": "/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
  },
  "sourceFiles": [
    {
      "executionId": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
      "filepath": "/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"
    }
  ],
  "newerVersionAt": null,
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 20480,
  "currentVersionId": "9b1d3f5a-7c2e-4a6c-8e0f-1b3d5f7a9c2e",
  "digest": "WyI5YjFkM2Y1YS03YzJlLTRhNmMtOGUwZi0xYjNkNWY3YTljMmUiLCI3MTJkYzYzYjIzNzA3YmM1NWQyMWM1M2M0YmFkOWJhN2IxMWRmN2I3MDQ3MzRkZTZjNmVmNmNmNzMwMDMxN2M0Il0",
  "createdAt": "2026-11-10T01:00:00.000Z",
  "updatedAt": "2026-11-12T01:00:00.000Z"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                                                   |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or fileId is not a UUID, or baseDigest is missing, empty, or not a string                                                                                                                                                                           |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                                               |
| `403`  | `insufficient_scope`     | The project:write scope is missing                                                                                                                                                                                                                            |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                                        |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                                            |
| `404`  | `file_not_found`         | The file does not exist or was deleted, or you are not a member of the project                                                                                                                                                                                |
| `409`  | `stale_base`             | The version of the file changed after you got it                                                                                                                                                                                                              |
| `409`  | `file_in_use`            | The file is bound to a step of a placement                                                                                                                                                                                                                    |
| `409`  | `no_source_file`         | The file was not copied in from an execution output                                                                                                                                                                                                           |
| `409`  | `source_file_missing`    | None of the checked outputs (checked in the same way as newerVersionAt) can be read, or they no longer exist                                                                                                                                                  |
| `409`  | `type_mismatch`          | The extension of the name of the newest output found differs from the extension of the name of this file (copy that output in as a new file with POST /v1/projects/{projectId}/library/copy, with executionId and filepath and without fileId and baseDigest) |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                                                       |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                                                          |

### DELETE`/v1/projects/{projectId}/library/{fileId}`

Deletes a file. Only owners can call this API.

#### Query Parameters

| Parameter | Type     | Default   | Description                                                        |
| --------- | -------- | --------- | ------------------------------------------------------------------ |
| `force`   | `string` | `"false"` | "true" deletes it even when placements bind it ("true" or "false") |

- When placements bind the file, `409 Conflict` (`file_in_use`) is returned (the number of placement steps using it is in the message). It can be deleted with `force=true`. If a binding is saved between the check and the deletion, the file may be deleted even without `force`.
- The bindings of placements remain after the deletion. A deleted file is no longer passed from the next start, for both workflow steps and cycle sweeps.
- It is kept in the records (audit trail).

#### Request Example

**Delete project library file**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6?force=false" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  headers={"Authorization": f"Bearer {token}"},
  params={"force": "false"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6" + "?force=false",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/library/8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field     | Type      | Description            |
| --------- | --------- | ---------------------- |
| `fileId`  | `string`  | ID of the deleted file |
| `deleted` | `boolean` | true                   |

#### Response Example

```json
{
  "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
  "deleted": true
}
```

#### Error Responses

| Status | code                 | Description                                                                    |
| ------ | -------------------- | ------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or fileId is not a UUID, or force is not "true" or "false"           |
| `403`  | `insufficient_scope` | The project:write scope is missing                                             |
| `403`  | `forbidden`          | Called with a system integration token                                         |
| `403`  | `owner_only`         | A member who is not an owner                                                   |
| `403`  | `sso_required`       | The user does not sign in with SSO                                             |
| `404`  | `file_not_found`     | The file does not exist or was deleted, or you are not a member of the project |
| `409`  | `file_in_use`        | Placements bind the file (it can be deleted with force=true)                   |

### PUT`/v1/projects/{projectId}/placements/{placementId}/library-bindings`

Binds files of the project library to a step of a placement. Bound files are passed to the workspace under the specified names when that step runs. Only owners can call this API.

#### Request Body

| Field                      | Type     | Required | Description                                                                                                                                                                                                                  |
| -------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`               | `string` | Yes      | The digest of the placement                                                                                                                                                                                                  |
| `stepId`                   | `string` | —        | ID of the step to bind (a step of the placement). Can be omitted for a placement with one step                                                                                                                               |
| `bindings`                 | `array`  | Yes      | All bindings of the step (up to 20). They are replaced with the list you send. Send \[] to remove them                                                                                                                       |
| `bindings[].fileId`        | `string` | Yes      | ID of a file in the project library                                                                                                                                                                                          |
| `bindings[].workspaceName` | `string` | Yes      | The name in the workspace. A file name only (no folders), and it cannot be repeated in the same list. Names that are not collected as execution outputs, such as names starting with "." or ending with .log, cannot be used |

- When saved, the input files of the executions of that Agent that have not started yet are also remade (it takes effect from the next start).
- It is kept in the records (audit trail) as a change to the definition (the caller is recorded. In a tenant that requires approval for definition changes, it is recorded through the approval).

#### Request Example

**Update placement library bindings**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
  "bindings": [
    {
      "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
      "workspaceName": "rules.xlsx"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.put(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU', 'bindings': [{'fileId': '8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6', 'workspaceName': 'rules.xlsx'}]},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings",
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "bindings": [{"fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6", "workspaceName": "rules.xlsx"}]}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU", "bindings": [{"fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6", "workspaceName": "rules.xlsx"}]}`)
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/library-bindings", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response (200 OK)

| Field                | Type             | Description                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement`          | `object`         | The placement after the change (with a new digest)                                                                                                                                                                                                                                                                                |
| `definitionApproval` | `object \| null` | When the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see [Definition approval fields](#definition-approval-object)). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once |

#### Response Example

```json
{
  "placement": {
    "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
    "displayOrder": 0,
    "name": "Accounting Agent",
    "description": "Matches invoice amounts against line items",
    "goal": "Match invoice amounts against line items and report differences",
    "guardrail": "Do not change amounts",
    "skills": [
      {
        "skillId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "name": "Invoice reading"
      }
    ],
    "skillCount": 1,
    "playbookId": null,
    "playbookName": null,
    "inputFiles": [],
    "stepIds": [
      "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
    ],
    "sweeps": [],
    "runtimeConfigs": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "runtimeConfig": null
      }
    ],
    "libraryBindings": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "fileId": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6",
        "workspaceName": "rules.xlsx"
      }
    ],
    "memoryOrgId": null,
    "memoryJobId": null,
    "instructionAddendum": null,
    "agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "isShared": false,
    "runtimeKind": "autonomous",
    "marketplaceAgentId": null,
    "exclusiveToThisProject": true,
    "agentStopped": false,
    "relink": null,
    "digest": "IZLY0-rGPDZhcpRHsCLwX61hXt7-k8aLazv0kMeuL9U"
  },
  "definitionApproval": null
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                     |
| ------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | projectId, placementId, or stepId is not a UUID, baseDigest is missing, empty, or not a string, stepId is required but missing, or bindings has the wrong form, number, or names                |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                 |
| `400`  | `step_not_found`               | stepId is not a step of this placement                                                                                                                                                          |
| `400`  | `file_not_found`               | A file in bindings is not in the project library (including deleted files)                                                                                                                      |
| `403`  | `insufficient_scope`           | The project:write scope is missing                                                                                                                                                              |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                          |
| `403`  | `owner_only`                   | A member who is not an owner                                                                                                                                                                    |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                              |
| `404`  | `placement_not_found`          | The placement does not exist, it belongs to another project, or you are not a member of the project                                                                                             |
| `409`  | `stale_base`                   | The placement changed after you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest |
| `409`  | `name_taken`                   | Another placement uses the same workspace name for a different file                                                                                                                             |
| `413`  | `body_too_large`               | The body exceeds 16 KiB                                                                                                                                                                         |
| `415`  | `unsupported_media_type`       | The Content-Type of the body is not application/json                                                                                                                                            |
| `409`  | `definition_invalid`           | Laid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result        |
| `503`  | `approval_setting_unavailable` | The definition approval setting cannot be confirmed. Retry after a while                                                                                                                        |
| `503`  | `definition_busy`              | Another change to the same definition is in progress. Retry after a while                                                                                                                       |

## Records (Audit Trail)

A list of certain operations and events in a project (review decisions, changes to execution rules and members, tool records in executions, and so on). The setting changes that are kept are changes to execution rules, reviewers, the review method, <!-- -->members, project webhooks, and "Start by email"<!-- --> (including changes made on the screen). Changes to the project definition (basic information, execution rules, steps, placements, triggers, app and email notifications, and connectors) are kept field by field as `project.definition_changed` when a definition version is recorded, as the difference from the previous version (long fields such as the description and goal are kept as their length only). <!-- -->Changes to the library (Agents, playbooks, and skills) and changes<!-- --> to sweeps and to outgoing webhook notifications are not kept.

### Endpoint List

| メソッド | エンドポイント                          | 説明                            | Scope (SaaS)   |
| ---- | -------------------------------- | ----------------------------- | -------------- |
| GET  | `/v1/projects/{projectId}/audit` | Get the records (audit trail) | `project:read` |

### GET`/v1/projects/{projectId}/audit`

Gets the records (audit trail), newest first. Cursor-based pagination is supported.

#### Query Parameters

| Parameter | Type      | Default | Description                                                                                        |
| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------- |
| `kind`    | `string`  | `—`     | Filter by kind of record (for example, "policy.changed", "improvement.applied", or "tool.invoked") |
| `run_id`  | `string`  | `—`     | Filter to the records of this workflow run (UUID)                                                  |
| `q`       | `string`  | `—`     | Filter by text (up to 100 characters)                                                              |
| `limit`   | `integer` | `50`    | Number of items per page (1-100)                                                                   |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                             |

#### Request Example

**List audit events**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit?kind=policy.changed&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "policy.changed", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit" + "?kind=policy.changed&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit?kind=policy.changed&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                  | Type             | Description                                                                                                                                                                    |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `events`               | `array`          | Array of records                                                                                                                                                               |
| `events[].eventId`     | `number`         | Record ID                                                                                                                                                                      |
| `events[].occurredAt`  | `string \| null` | Time (ISO 8601)                                                                                                                                                                |
| `events[].eventType`   | `string \| null` | Kind of record                                                                                                                                                                 |
| `events[].actorKind`   | `string \| null` | Kind of recorder: "agent", "human", "system", "human\_external", "mail\_external", or "unknown"                                                                                |
| `events[].actorRef`    | `string \| null` | Recorder. A user ID when actorKind is "human"; otherwise a reference (client:\<integration ID> for a system integration, mail:\<hash> for an external email sender, and so on) |
| `events[].decision`    | `string \| null` | Decision or result                                                                                                                                                             |
| `events[].reason`      | `string \| null` | Reason                                                                                                                                                                         |
| `events[].executionId` | `string \| null` | Execution ID                                                                                                                                                                   |
| `events[].runId`       | `string \| null` | ID of the workflow run                                                                                                                                                         |
| `events[].stepName`    | `string \| null` | Step name                                                                                                                                                                      |
| `events[].metadata`    | `object`         | Contents of each record. Field names are returned as recorded. {} for a record without contents                                                                                |
| `hasMore`              | `boolean`        | Whether there is a next page                                                                                                                                                   |
| `cursor`               | `string`         | Cursor for the next page. Included only when hasMore is true                                                                                                                   |

- Identify rows of system integrations by `client:<integration ID>` in `actorRef`. Read the display name of an integration from `actorLabel` in the execution history or the execution result.
- Some records during an execution (`context.manifest`, `runtime.*`, and so on) are not included. Read them in the execution timeline.

#### Response Example

```json
{
  "events": [
    {
      "eventId": 1042,
      "occurredAt": "2026-11-18T04:20:11.000Z",
      "eventType": "policy.changed",
      "actorKind": "human",
      "actorRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "decision": null,
      "reason": null,
      "executionId": null,
      "runId": null,
      "stepName": null,
      "metadata": {}
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                                                                       |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId or run\_id is not a UUID, run\_id and runId have different values, kind is not in the form of a kind of record, q exceeds 100 characters, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                                                                                 |
| `403`  | `forbidden`          | Called with a system integration token                                                                                                                                            |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                                                                                |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                                                                                                               |

## KPI

Gets the same values as "Results of this work" in the overview on the screen (the per-step `steps` are the values shown under "Metrics" in "Workflow shape"; the values of the review steps alone are also in `gates`). For how they are counted, see the [Results Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/results-ref.md) (for the per-step values, [Figures by step](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/results-ref.md#figures-by-step)).

### Endpoint List

| メソッド | エンドポイント                               | 説明                 | Scope (SaaS)   |
| ---- | ------------------------------------- | ------------------ | -------------- |
| GET  | `/v1/projects/{projectId}/kpi`        | Get the KPIs       | `project:read` |
| GET  | `/v1/projects/{projectId}/kpi/trends` | Get the KPI trends | `project:read` |

### GET`/v1/projects/{projectId}/kpi`

Gets the KPIs of a project. Project members and people with the organization operations role can read them (even for a shared project, anyone else gets 404).

#### Query Parameters

| Parameter | Type      | Default | Description                                        |
| --------- | --------- | ------- | -------------------------------------------------- |
| `days`    | `integer` | `30`    | Period (the most recent days). One of 7, 30, or 90 |

#### Request Example

**Get project KPI**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi",
  headers={"Authorization": f"Bearer {token}"},
  params={"days": "30"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi" + "?days=30",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                     | Type             | Description                                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `days`                    | `number`         | Period (days)                                                                                                                                                                                                                                                                                                                                     |
| `successRate`             | `number \| null` | Agent completion rate (0 to 1; completed ÷ finished). null when finished is 0                                                                                                                                                                                                                                                                     |
| `successRateStatus`       | `string`         | "ok" (final), "incomplete" (provisional because a record is insufficient), or "none" (no record is insufficient and finished is 0)                                                                                                                                                                                                                |
| `succeeded`               | `number`         | Number of completed executions                                                                                                                                                                                                                                                                                                                    |
| `denominator`             | `number`         | Number of finished executions (Completed plus "Failed / needs action"; executions that finished with no change are not counted)                                                                                                                                                                                                                   |
| `executions`              | `number`         | Number of finished executions (the sum of denominator and noChange)                                                                                                                                                                                                                                                                               |
| `noChange`                | `number`         | Number of executions that finished with no change (the result is completed and the reason is "no\_change"). Not counted in finished or successful completions                                                                                                                                                                                     |
| `outcomes`                | `object`         | Numbers per outcome (completed, incomplete, failed, timeout, stopped, denied, and skipped). completed includes executions that finished with no change                                                                                                                                                                                            |
| `excluded`                | `object`         | Numbers not counted (skipped, running, missing, unmeasured, and connectionConfirm). connectionConfirm is the number of executions stopped for a connection confirmation; they are not included in the Agent completion rate, finished, completed successfully, the number of finished executions, the numbers per outcome, or the processing time |
| `durationP95Minutes`      | `number \| null` | Processing time guide (p95, minutes)                                                                                                                                                                                                                                                                                                              |
| `runs`                    | `object`         | Numbers of workflow runs (total, closedDone, closedFailed, closedRejected, and cancelled) and p95Minutes                                                                                                                                                                                                                                          |
| `gates`                   | `array`          | Results per review step (stepId, position, name, mode, total, approvalRate, and sendBackRate). When steps is an array and the gate of a review step's row is not null, total, approvalRate, and sendBackRate are the same as in that gate                                                                                                         |
| `steps`                   | `array \| null`  | Results per step. Lists the enabled steps in position order (stepId, position, name, defaultZone, agent, gate, and automation). Only the one of agent, gate, and automation that matches the type of the step is set, and the others are null. For a branch step, all of them are null. null when it cannot be obtained                           |
| `steps[].name`            | `string`         | Step name (for a step without a name, a name made in the project's language, or in the service's default language if the project has none)                                                                                                                                                                                                        |
| `steps[].defaultZone`     | `string \| null` | Step type. One of "ai" (run by an Agent), "gate" (review step), "automation" (external automation) and "branch" (branch)                                                                                                                                                                                                                          |
| `steps[].agent`           | `object \| null` | Results of an Agent step: the same items as the Agent completion rate above (executions, succeeded, denominator, noChange, successRate, successRateStatus, outcomes, excluded, and durationP95Minutes), counted from the executions of that step only                                                                                             |
| `steps[].gate`            | `object \| null` | Results of a review step (mode, total, approvalRate, sendBackRate, waitMedianMinutes, and deadlineDecisions). deadlineDecisions is counted in the same way as human.deadlineDecisions, from the review requests of that step only; as with human.deadlineDecisions, rate is null when total is 0                                                  |
| `steps[].automation`      | `object \| null` | Send counts of an external automation step (total; sent: sent successfully; failed: failed to send). Not included in the Agent completion rate                                                                                                                                                                                                    |
| `human`                   | `object`         | Review handling (reviewsPerRun, gateWaitMedianMinutes, interventions, and deadlineDecisions)                                                                                                                                                                                                                                                      |
| `human.deadlineDecisions` | `object \| null` | Of the reviews with a deadline, how many a person decided in time (total: decided or past the deadline; onTime: decided by a person by the deadline; rate: onTime / total, null when total is 0). Automatic decisions at the deadline are not counted as on time                                                                                  |
| `workSteps`               | `object`         | Numbers counted the same way as billing steps (executions, billableExecutions, excludedExecutions, toolCalls, steps, stepsUnknown, and formulaVersion). workSteps.steps is the number of billing steps, not the per-step results in steps                                                                                                         |

The Agent completion rate, `runs`, `gates`, `steps`, and `human` count executions, workflow runs, and review requests that started in the period.<!-- --> `workSteps` counts executions that finished in the period. Because they count different executions, `executions` and `workSteps.executions` do not always match.

#### Error Responses

| Status | code                 | Description                                          |
| ------ | -------------------- | ---------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID, or days is not 7, 30, or 90 |
| `403`  | `insufficient_scope` | The project:read scope is missing                    |
| `403`  | `forbidden`          | Called with a system integration token               |
| `403`  | `sso_required`       | The user does not sign in with SSO                   |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member  |

#### Response Example

```json
{
  "days": 30,
  "successRate": 0.9318,
  "successRateStatus": "ok",
  "succeeded": 41,
  "denominator": 44,
  "executions": 46,
  "noChange": 2,
  "outcomes": {
    "completed": 43,
    "incomplete": 2,
    "failed": 1,
    "timeout": 0,
    "stopped": 0,
    "denied": 0,
    "skipped": 1
  },
  "excluded": {
    "skipped": 1,
    "running": 1,
    "missing": 2,
    "unmeasured": 0,
    "connectionConfirm": 0
  },
  "durationP95Minutes": 14,
  "runs": {
    "total": 24,
    "closedDone": 20,
    "closedFailed": 2,
    "closedRejected": 1,
    "cancelled": 1,
    "p95Minutes": 22
  },
  "gates": [
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 2,
      "name": "Amount check",
      "mode": "blocking",
      "total": 17,
      "approvalRate": 0.88,
      "sendBackRate": 0.12
    }
  ],
  "steps": [
    {
      "stepId": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70812",
      "position": 1,
      "name": "Read invoices",
      "defaultZone": "ai",
      "agent": {
        "executions": 46,
        "succeeded": 41,
        "denominator": 44,
        "noChange": 2,
        "successRate": 0.9318,
        "successRateStatus": "ok",
        "durationP95Minutes": 14,
        "outcomes": {
          "completed": 43,
          "incomplete": 2,
          "failed": 1,
          "timeout": 0,
          "stopped": 0,
          "denied": 0,
          "skipped": 1
        },
        "excluded": {
          "skipped": 1,
          "running": 1,
          "missing": 2,
          "unmeasured": 0,
          "connectionConfirm": 0
        }
      },
      "gate": null,
      "automation": null
    },
    {
      "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "position": 2,
      "name": "Amount check",
      "defaultZone": "gate",
      "agent": null,
      "gate": {
        "mode": "blocking",
        "total": 17,
        "approvalRate": 0.88,
        "sendBackRate": 0.12,
        "waitMedianMinutes": 35,
        "deadlineDecisions": {
          "total": 15,
          "onTime": 14,
          "rate": 0.9333
        }
      },
      "automation": null
    },
    {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f70819a2b",
      "position": 3,
      "name": "Send to accounting system",
      "defaultZone": "automation",
      "agent": null,
      "gate": null,
      "automation": {
        "total": 20,
        "sent": 19,
        "failed": 1
      }
    }
  ],
  "human": {
    "reviewsPerRun": 0.7,
    "gateWaitMedianMinutes": 35,
    "interventions": 17,
    "deadlineDecisions": {
      "total": 15,
      "onTime": 14,
      "rate": 0.9333
    }
  },
  "workSteps": {
    "executions": 46,
    "billableExecutions": 44,
    "excludedExecutions": 2,
    "toolCalls": 312,
    "steps": 98,
    "stepsUnknown": 0,
    "formulaVersion": "v2"
  }
}
```

### GET`/v1/projects/{projectId}/kpi/trends`

Gets the KPI trends (comparison with the previous period, daily and weekly series, and the backlog of review requests). Returns this one project, counted the same way as "Cross-project KPIs" in the admin console. Project members and people with the organization operations role can read them (even for a shared project, anyone else gets 404). The period cannot be chosen (there are no query parameters).

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Request Example

**Get project KPI trends**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi/trends \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi/trends",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi/trends",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi/trends", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                          | Type             | Description                                                                                       |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------- |
| `week`                         | `object`         | Metrics for the last 7 days (current) and the 7 days before them (previous)                       |
| `month`                        | `object`         | Metrics for the last 30 days (current) and the 30 days before them (previous)                     |
| `backlog`                      | `object`         | The current backlog of review requests                                                            |
| `backlog.assigned`             | `number`         | Number of review requests not yet decided                                                         |
| `backlog.oldestWaitingMinutes` | `number \| null` | The waiting time (minutes) of the one that has waited longest among them. null when there is none |
| `backlog.overdue`              | `number`         | Number of those past their due date                                                               |
| `series`                       | `object`         | Series                                                                                            |
| `series.day`                   | `array`          | Daily metrics (30 points for the last 30 days, oldest first)                                      |
| `series.week`                  | `array`          | Weekly metrics (12 points for the last 12 weeks, oldest first; weeks start on Monday)             |
| `series.day[].bucket`          | `string`         | The date of the day (YYYY-MM-DD). series.week\[].bucket is the date of the Monday of the week     |

- `week` and `month` are counted back from the time of the call.
- The days and weeks of `series` are divided in Japan time. Days and weeks with nothing to count are returned as 0. The points for today and this week cover up to the time of the call.
- Which period and which point an item falls in is decided by when executions and workflow runs started, when review requests were created, and when improvement ideas were applied.

Metrics (`current` and `previous` of `week` and `month`, and one point of `series`):

| Field                       | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executions`                | `number`         | Number of finished executions (the sum of denominator and the executions that finished with no change)                                                                                                                                                                                                                                                                                                     |
| `denominator`               | `number`         | Number of finished executions (Completed plus "Failed / needs action"; executions that finished with no change are not counted)                                                                                                                                                                                                                                                                            |
| `succeeded`                 | `number`         | Number of completed executions                                                                                                                                                                                                                                                                                                                                                                             |
| `successRate`               | `number \| null` | Agent completion rate (0 to 1; succeeded ÷ denominator). null when denominator is 0                                                                                                                                                                                                                                                                                                                        |
| `missing`                   | `number`         | Number of executions that finished without a recorded result (insufficient record)                                                                                                                                                                                                                                                                                                                         |
| `excludedConnectionConfirm` | `number`         | Number of executions stopped for a connection confirmation. They are not included in executions, denominator, succeeded, missing, durationMedianMinutes, or failures                                                                                                                                                                                                                                       |
| `runs`                      | `number`         | Number of workflow runs that started                                                                                                                                                                                                                                                                                                                                                                       |
| `humanDecisions`            | `number`         | Number of review requests decided by a person (those decided automatically are not counted)                                                                                                                                                                                                                                                                                                                |
| `interventionRate`          | `number \| null` | humanDecisions ÷ runs. null when runs is 0                                                                                                                                                                                                                                                                                                                                                                 |
| `improvements`              | `number`         | Number of improvement ideas applied (the number of improvement.applied in the records (audit trail))                                                                                                                                                                                                                                                                                                       |
| `durationMedianMinutes`     | `number \| null` | Median duration (minutes) of finished executions. Executions without a recorded result, and stopped or skipped executions, are not counted. null when there is none                                                                                                                                                                                                                                        |
| `failures`                  | `object`         | Numbers of failures (incomplete, failed, timeout, and denied) per fix target. The keys are goal, skill, handoff, not\_assigned, connection, rule, guardrail, external, and unknown (the same values as envelope.completionReport.fixTarget in the execution result) and platform (no fix target, with a platform-side failure). A failure with neither a fix target nor a platform-side failure is unknown |

#### Response Example

```json
{
  "week": {
    "current": {
      "executions": 12,
      "denominator": 11,
      "succeeded": 10,
      "successRate": 0.9091,
      "missing": 1,
      "excludedConnectionConfirm": 0,
      "runs": 6,
      "humanDecisions": 4,
      "interventionRate": 0.6667,
      "improvements": 1,
      "durationMedianMinutes": 6.5,
      "failures": {
        "goal": 0,
        "skill": 1,
        "handoff": 0,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    },
    "previous": {
      "executions": 9,
      "denominator": 9,
      "succeeded": 7,
      "successRate": 0.7778,
      "missing": 0,
      "excludedConnectionConfirm": 0,
      "runs": 5,
      "humanDecisions": 5,
      "interventionRate": 1,
      "improvements": 0,
      "durationMedianMinutes": 8,
      "failures": {
        "goal": 1,
        "skill": 0,
        "handoff": 1,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    }
  },
  "month": {
    "current": {
      "executions": 48,
      "denominator": 46,
      "succeeded": 41,
      "successRate": 0.8913,
      "missing": 2,
      "excludedConnectionConfirm": 0,
      "runs": 24,
      "humanDecisions": 17,
      "interventionRate": 0.7083,
      "improvements": 3,
      "durationMedianMinutes": 7,
      "failures": {
        "goal": 1,
        "skill": 3,
        "handoff": 1,
        "not_assigned": 0,
        "connection": 0,
        "rule": 0,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    },
    "previous": {
      "executions": 40,
      "denominator": 40,
      "succeeded": 33,
      "successRate": 0.825,
      "missing": 0,
      "excludedConnectionConfirm": 0,
      "runs": 20,
      "humanDecisions": 18,
      "interventionRate": 0.9,
      "improvements": 2,
      "durationMedianMinutes": 8.5,
      "failures": {
        "goal": 3,
        "skill": 1,
        "handoff": 2,
        "not_assigned": 0,
        "connection": 0,
        "rule": 2,
        "guardrail": 0,
        "external": 0,
        "unknown": 0,
        "platform": 0
      }
    }
  },
  "backlog": {
    "assigned": 2,
    "oldestWaitingMinutes": 185,
    "overdue": 1
  },
  "series": {
    "day": [
      {
        "bucket": "2026-11-17",
        "executions": 3,
        "denominator": 3,
        "succeeded": 3,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 2,
        "humanDecisions": 1,
        "interventionRate": 0.5,
        "improvements": 0,
        "durationMedianMinutes": 5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      },
      {
        "bucket": "2026-11-18",
        "executions": 1,
        "denominator": 1,
        "succeeded": 1,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 1,
        "humanDecisions": 0,
        "interventionRate": 0,
        "improvements": 0,
        "durationMedianMinutes": 4,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      }
    ],
    "week": [
      {
        "bucket": "2026-11-09",
        "executions": 12,
        "denominator": 11,
        "succeeded": 10,
        "successRate": 0.9091,
        "missing": 1,
        "excludedConnectionConfirm": 0,
        "runs": 6,
        "humanDecisions": 4,
        "interventionRate": 0.6667,
        "improvements": 1,
        "durationMedianMinutes": 6.5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      },
      {
        "bucket": "2026-11-16",
        "executions": 4,
        "denominator": 4,
        "succeeded": 4,
        "successRate": 1,
        "missing": 0,
        "excludedConnectionConfirm": 0,
        "runs": 3,
        "humanDecisions": 1,
        "interventionRate": 0.3333,
        "improvements": 0,
        "durationMedianMinutes": 5,
        "failures": {
          "goal": 0,
          "skill": 1,
          "handoff": 0,
          "not_assigned": 0,
          "connection": 0,
          "rule": 0,
          "guardrail": 0,
          "external": 0,
          "unknown": 0,
          "platform": 0
        }
      }
    ]
  }
}
```

In the example, only two points each of `series.day` and `series.week` are shown (in practice `series.day` has 30 points and `series.week` has 12).

#### Error Responses

| Status | code                 | Description                                         |
| ------ | -------------------- | --------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID                             |
| `403`  | `insufficient_scope` | The project:read scope is missing                   |
| `403`  | `forbidden`          | Called with a system integration token              |
| `403`  | `sso_required`       | The user does not sign in with SSO                  |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member |
| `504`  | `upstream_timeout`   | Counting did not finish in time (try again later)   |

## Review Requests

A review request is created when a workflow reaches a review step, or when an Agent step returns "Not allowed by rules" or "Failed (reported by agent)" and that step is set to ask for review.<!-- --> It is also created when an Agent is about to use a connector that requires human confirmation (`confirmMode` of the connector), in a workflow step or in a cycle sweep (connection confirmation).<!-- --> The reviewers decide whether to proceed, send it back, or reject it<!-- -->; for a connection confirmation, they can only proceed or reject<!-- -->. It is the same as a review request on the screen.

- Reviewers (the reviewers when the review request was created who are still members of the project), their delegates during the delegation period, and the owners of the project can read it. Other users get `404 Not Found` (`workitem_not_found`).
- Only reviewers and their delegates during the delegation period can decide. An owner who is neither cannot (`403 Forbidden`, `not_gate_owner`). The due date can also be extended by owners, operators, and people with the organization operations role. A reviewer sets a delegate in the settings screen (Out of office): one user in the same organization, for a set period. The delegate does not have to be a member of the project.

### Endpoint List

| メソッド  | エンドポイント                               | 説明                                      | Scope (SaaS)     |
| ----- | ------------------------------------- | --------------------------------------- | ---------------- |
| GET   | `/v1/workitems`                       | Get the list of review requests         | `project:read`   |
| GET   | `/v1/workitems/{workItemId}`          | Get a review request                    | `project:read`   |
| POST  | `/v1/workitems/{workItemId}/decision` | Decide a review request                 | `project:decide` |
| PATCH | `/v1/workitems/{workItemId}`          | Extend the due date of a review request | `project:decide` |

### GET`/v1/workitems`

Gets the review requests you can read, most recently updated first, across projects. Cursor-based pagination is supported.

#### Query Parameters

| Parameter    | Type      | Default | Description                                                                                                                                                 |
| ------------ | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`     | `string`  | `—`     | Filter by state: "assigned" (waiting for review), "done" (proceeded or sent back), or "cancelled" (rejected, or cancelled because the workflow run stopped) |
| `state`      | `string`  | `—`     | Filter by "open" (assigned and not yet decided) or "closed" (anything else)                                                                                 |
| `project_id` | `string`  | `—`     | Filter to the review requests of this project (UUID)                                                                                                        |
| `limit`      | `integer` | `50`    | Number of items per page (1-100)                                                                                                                            |
| `cursor`     | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                                                                                      |

#### Request Example

**List work items**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems?state=open&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems",
  headers={"Authorization": f"Bearer {token}"},
  params={"state": "open", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems" + "?state=open&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems?state=open&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                         | Type              | Description                                                                                                               |
| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `workitems`                   | `array`           | Array of review requests                                                                                                  |
| `workitems[].workItemId`      | `string`          | Review request ID (UUID)                                                                                                  |
| `workitems[].title`           | `string \| null`  | Title                                                                                                                     |
| `workitems[].status`          | `string \| null`  | "assigned", "done", or "cancelled"                                                                                        |
| `workitems[].projectId`       | `string \| null`  | Project ID                                                                                                                |
| `workitems[].projectName`     | `string \| null`  | Project name                                                                                                              |
| `workitems[].decision`        | `string \| null`  | Decision: "proceed", "send\_back", or "reject". null before a decision                                                    |
| `workitems[].requesterUserId` | `string \| null`  | User ID of the requester                                                                                                  |
| `workitems[].expiresAt`       | `string \| null`  | Review deadline (ISO 8601)                                                                                                |
| `workitems[].gateMode`        | `string \| null`  | Review method: "blocking" (wait for the reviewer's decision) or "notify\_only" (proceed automatically after the deadline) |
| `workitems[].overdue`         | `boolean \| null` | Whether the deadline has passed                                                                                           |
| `workitems[].decidedAt`       | `string \| null`  | When it was decided (ISO 8601)                                                                                            |
| `workitems[].createdAt`       | `string \| null`  | Creation time (ISO 8601)                                                                                                  |
| `workitems[].updatedAt`       | `string \| null`  | Update time (ISO 8601)                                                                                                    |
| `workitems[].canDecide`       | `boolean`         | Whether you can decide (true for a reviewer, or for their delegate during the delegation period)                          |
| `hasMore`                     | `boolean`         | Whether there is a next page                                                                                              |
| `cursor`                      | `string`          | Cursor for the next page. Included only when hasMore is true                                                              |

#### Response Example

```json
{
  "workitems": [
    {
      "workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
      "title": "Check invoices with differences",
      "status": "assigned",
      "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
      "projectName": "Invoice reconciliation",
      "decision": null,
      "requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "expiresAt": "2026-11-20T09:00:00.000Z",
      "gateMode": "blocking",
      "overdue": false,
      "decidedAt": null,
      "createdAt": "2026-11-18T01:34:40.000Z",
      "updatedAt": "2026-11-18T01:34:40.000Z",
      "canDecide": true
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                                                                               |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | status or state is not one of the values above, project\_id is not a UUID, project\_id and projectId have different values, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                                                                                         |
| `403`  | `forbidden`          | Called with a system integration token                                                                                                                    |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                                                                                        |

### GET`/v1/workitems/{workItemId}`

Gets a review request, with the material for the review, its history, and the destinations you can choose.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                       |
| ------------ | -------- | -- | ------------------------ |
| `workItemId` | `string` | 必須 | Review request ID (UUID) |

#### Request Example

**Get work item**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                                   | Type               | Description                                                                                                                                                                                                                    |
| --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workitem`                              | `object`           | The review request: the fields of an item in the list (workItemId, title, status, projectId, decision, requesterUserId, expiresAt, gateMode, overdue, decidedAt, createdAt, updatedAt, and canDecide) and the following fields |
| `workitem.description`                  | `string \| null`   | Description                                                                                                                                                                                                                    |
| `workitem.runId`                        | `string \| null`   | ID of the workflow run                                                                                                                                                                                                         |
| `workitem.runStepId`                    | `string \| null`   | Execution ID of the step that asked for the review (rs:\<number>; the same form as executionId in the execution history). null for a connection confirmation in a cycle                                                        |
| `workitem.stepId`                       | `string \| null`   | ID of the step that asked for the review (a review step, an Agent step that asked for a review because of its outcome, or an Agent step stopped for a connection confirmation)                                                 |
| `workitem.approverUserIds`              | `array`            | Array of user IDs of the reviewers (the reviewers when the review request was created)                                                                                                                                         |
| `workitem.overdueAction`                | `string \| null`   | After the deadline: "none", "proceed", "send\_back", or "reject". A connection confirmation is "none", but it is decided as rejected after the deadline                                                                        |
| `workitem.evidence`                     | `object \| null`   | Material for the review (see the table below)                                                                                                                                                                                  |
| `workitem.decidedByKind`                | `string \| null`   | Kind of what decided (for example, "human"). null before a decision                                                                                                                                                            |
| `workitem.decidedByRef`                 | `string \| null`   | What decided. A user ID when decidedByKind is "human". An automatic decision after the deadline and the like is a system:… reference. null before a decision                                                                   |
| `workitem.decisionReason`               | `string \| null`   | Reason for the decision                                                                                                                                                                                                        |
| `workitem.sendBackToStepId`             | `string \| null`   | ID of the step sent back to                                                                                                                                                                                                    |
| `workitem.decisionResult`               | `object \| null`   | Result of the decision (decision, at, completesRun, sendBackToStepId, destinationId, sendBackFiles, and destinationStepId). completesRun is whether proceeding finished the workflow run                                       |
| `workitem.decisionResult.sendBackFiles` | `object[] \| null` | Files attached to a send-back (fileId, filename). null when none were attached                                                                                                                                                 |
| `activities`                            | `array`            | History (newest first, up to 100 items)                                                                                                                                                                                        |
| `activities[].activityId`               | `number \| null`   | History ID                                                                                                                                                                                                                     |
| `activities[].eventType`                | `string \| null`   | Kind of record                                                                                                                                                                                                                 |
| `activities[].decision`                 | `string \| null`   | Decision                                                                                                                                                                                                                       |
| `activities[].actorKind`                | `string \| null`   | Kind of recorder                                                                                                                                                                                                               |
| `activities[].actorRef`                 | `string \| null`   | Recorder. A user ID when actorKind is "human"; otherwise a reference such as system:…                                                                                                                                          |
| `activities[].onBehalfOfRef`            | `string \| null`   | When a delegate decided, the user ID of the reviewer they acted for. null when, for example, the reviewer decided themselves                                                                                                   |
| `activities[].reasonCode`               | `string \| null`   | Reason ("branch\_undecided" when a branch could not decide and a person is asked to choose)                                                                                                                                    |
| `activities[].conversationId`           | `string \| null`   | Conversation ID                                                                                                                                                                                                                |
| `activities[].metadata`                 | `object`           | Contents of each record. Field names are returned as recorded (they may contain user IDs)                                                                                                                                      |
| `activities[].occurredAt`               | `string \| null`   | Time (ISO 8601)                                                                                                                                                                                                                |
| `gate`                                  | `object \| null`   | Information for the decision (see the table below)                                                                                                                                                                             |

Material for the review (`workitem.evidence`):

| Field              | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary`          | `string \| null` | Text for the review. Usually the output of the Agents of the reviewed step; when an Agent step asked for a review because of its outcome, a summary of the outcome and its reason. For a connection confirmation, the purpose of using the connector (written by the Agent)                                                                                                                       |
| `conversationId`   | `string \| null` | ID of the execution conversation of the reviewed step                                                                                                                                                                                                                                                                                                                                             |
| `files`            | `array`          | Files of the reviewed step (same form as deliverables in the conversation API. Get the content by passing filepath as path to Get the content of a file (GET /v1/projects/{projectId}/files/content))                                                                                                                                                                                             |
| `gateKind`         | `string \| null` | Kind of review: "review" (review), "manual" (manual work), or "connection" (connection confirmation: a person is asked to confirm before an Agent uses a connector; set with confirmMode of the connector)                                                                                                                                                                                        |
| `stepName`         | `string \| null` | Name of the step that asked for the review                                                                                                                                                                                                                                                                                                                                                        |
| `outcome`          | `string \| null` | Outcome of the execution of the reviewed step (see "Outcome Values" of executions)                                                                                                                                                                                                                                                                                                                |
| `executionId`      | `string \| null` | Execution ID of the reviewed step (can be read with Get the result of an execution)                                                                                                                                                                                                                                                                                                               |
| `reasonCode`       | `string \| null` | Reason for the outcome (when an Agent step asked for a review because of its outcome; "branch\_undecided" for a review where a branch could not decide and a person chooses)                                                                                                                                                                                                                      |
| `escalateToUserId` | `string \| null` | User ID of the contact after the deadline (a person who was a member when the review request was created)                                                                                                                                                                                                                                                                                         |
| `destinations`     | `array`          | Steps you can choose to proceed to (destinationId, label, and stepId). An empty array when not set. For a review raised by a branch step, branchRoute (where to go: {"kind": "lane", "laneId"} or {"kind": "merge"}) is also included (no key when absent)                                                                                                                                        |
| `connector`        | `object \| null` | For a connection confirmation, the connector the Agent was about to use (kind, connectionId, and name; same form as connectors\[] of Get a project). When the connector information could not be checked, kind and connectionId are null. null if it is not a connection confirmation                                                                                                             |
| `service`          | `string \| null` | For a connection confirmation, the name of the service of the connector the Agent was about to use. null if it is not a connection confirmation                                                                                                                                                                                                                                                   |
| `mode`             | `string \| null` | For a connection confirmation, the confirmation setting ("first\_per\_execution" or "always"; same values as confirmMode of the connector). null if it is not a connection confirmation                                                                                                                                                                                                           |
| `tool`             | `string \| null` | For a connection confirmation, the name of the tool the Agent was about to use (null when unknown). null if it is not a connection confirmation                                                                                                                                                                                                                                                   |
| `waitMinutes`      | `number \| null` | For a connection confirmation, how long to wait for it (minutes). null if it is not a connection confirmation                                                                                                                                                                                                                                                                                     |
| `handoff`          | `array`          | For each step before the reviewed step, the values and files passed to the next step. Each item has label (to tell the previous steps apart when there are several; null when there is one) and values, files, missing and truncated (the same shape as steps\[].handoff in getting a run). An empty array when the previous steps have no values and file roles for the next step (outputConfig) |

Information for the decision (`gate`):

| Field                   | Type              | Description                                                                                                                                                                                                                                                                            |
| ----------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contextVersion`        | `integer \| null` | The version of the work item. Send it as contextVersion in the decision. null for an older work item without a version; then omit contextVersion.                                                                                                                                      |
| `projectName`           | `string \| null`  | Project name                                                                                                                                                                                                                                                                           |
| `projectType`           | `string \| null`  | Project type                                                                                                                                                                                                                                                                           |
| `stepId`                | `string \| null`  | ID of the step that asked for the review                                                                                                                                                                                                                                               |
| `stepName`              | `string \| null`  | Name of the step that asked for the review                                                                                                                                                                                                                                             |
| `stepPosition`          | `number \| null`  | Position of the step that asked for the review                                                                                                                                                                                                                                         |
| `nextStep`              | `object \| null`  | The next step when proceeding (stepId, name, and position). null when there is no next step                                                                                                                                                                                            |
| `editableOutput`        | `string \| null`  | The reviewed output to correct, for a kind of work item that can be corrected. Correct this text and send it as editedOutput in the decision. null for a kind of work item that cannot be corrected. It does not tell whether you can still decide; see status and workitem.canDecide. |
| `sendBackDefaultStepId` | `string \| null`  | ID of the step sent back to when no send-back step is specified                                                                                                                                                                                                                        |
| `sendBackCandidates`    | `array`           | Steps you can specify as the send-back step (stepId, name, position, and sendBacks). sendBacks is the number of times sent back to that step                                                                                                                                           |
| `sendBackLimit`         | `number \| null`  | Maximum number of send-backs to one step                                                                                                                                                                                                                                               |
| `destinations`          | `array`           | Steps you can choose to proceed to (destinationId, label, stepId, stepName, and stepPosition). For a review raised by a branch step, branchRoute (where to go: {"kind": "lane", "laneId"} or {"kind": "merge"}) is also included (no key when absent)                                  |
| `lane`                  | `object \| null`  | Lane of the step that asked for the review (laneId, name, and position). null when there are no lanes                                                                                                                                                                                  |

#### Response Example

```json
{
  "workitem": {
    "workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
    "title": "Check invoices with differences",
    "status": "assigned",
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "decision": null,
    "requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "expiresAt": "2026-11-20T09:00:00.000Z",
    "gateMode": "blocking",
    "overdue": false,
    "decidedAt": null,
    "createdAt": "2026-11-18T01:34:40.000Z",
    "updatedAt": "2026-11-18T01:34:40.000Z",
    "canDecide": true,
    "description": "1 of the 12 invoices has an amount difference.",
    "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
    "runStepId": "rs:1843",
    "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "approverUserIds": [
      "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    ],
    "overdueAction": "none",
    "evidence": {
      "summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
      "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "files": [],
      "gateKind": "review",
      "stepName": "Amount check",
      "outcome": "completed",
      "executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
      "reasonCode": null,
      "escalateToUserId": null,
      "destinations": [],
      "connector": null,
      "service": null,
      "mode": null,
      "tool": null,
      "waitMinutes": null,
      "handoff": []
    },
    "decidedByKind": null,
    "decidedByRef": null,
    "decisionReason": null,
    "sendBackToStepId": null,
    "decisionResult": null
  },
  "activities": [
    {
      "activityId": 5301,
      "eventType": "gate.requested",
      "decision": "requested",
      "actorKind": "system",
      "actorRef": "system:completion-apply",
      "onBehalfOfRef": null,
      "reasonCode": "review",
      "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "metadata": {
        "workitem_id": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
        "run_id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
        "step_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "gate_mode": "blocking",
        "gate_kind": "review"
      },
      "occurredAt": "2026-11-18T01:34:40.000Z"
    }
  ],
  "gate": {
    "contextVersion": 1,
    "projectName": "Invoice reconciliation",
    "projectType": "workflow",
    "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "stepName": "Difference check",
    "stepPosition": 2,
    "nextStep": {
      "stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "name": "Difference report",
      "position": 3
    },
    "editableOutput": null,
    "sendBackDefaultStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
    "sendBackCandidates": [
      {
        "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
        "name": "Amount check",
        "position": 1,
        "sendBacks": 0
      }
    ],
    "sendBackLimit": 3,
    "destinations": [],
    "lane": null
  }
}
```

#### Error Responses

| Status | code                 | Description                                              |
| ------ | -------------------- | -------------------------------------------------------- |
| `400`  | `invalid_parameter`  | workItemId is not a UUID                                 |
| `403`  | `insufficient_scope` | The project:read scope is missing                        |
| `403`  | `forbidden`          | Called with a system integration token                   |
| `403`  | `sso_required`       | The user does not sign in with SSO                       |
| `404`  | `workitem_not_found` | The review request does not exist, or you cannot read it |

### POST`/v1/workitems/{workItemId}/decision`

Decides a review request. Only reviewers and their delegates during the delegation period can call it.

#### Request Body

| Field              | Type       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `decision`         | `string`   | Yes      | "proceed", "send\_back", or "reject"                                                                                                                                                                                                                                                                                                                                                           |
| `reason`           | `string`   | —        | Reason (up to 10000 characters). Required for "send\_back" and "reject"                                                                                                                                                                                                                                                                                                                        |
| `sendBackToStepId` | `string`   | —        | ID of the step to send back to (for "send\_back"; a step in sendBackCandidates of gate). If omitted, it is sent back to the step in sendBackDefaultStepId                                                                                                                                                                                                                                      |
| `sendBackFiles`    | `string[]` | —        | For send\_back: project library file IDs (up to 5). When the step you send back to runs again, they are placed in its workspace as input files under their library names (files deleted by then are not passed)                                                                                                                                                                                |
| `destinationId`    | `string`   | —        | Destination (for "proceed"; destinationId in destinations of gate; up to 64 characters). Required to proceed a review request that has destinations                                                                                                                                                                                                                                            |
| `editedOutput`     | `string`   | —        | The corrected output to proceed with ("proceed" only, and only for work items whose gate.editableOutput is not null). The next step gets this text instead of the reviewed output. Up to 20000 characters, not counting leading and trailing whitespace (the text is saved without them). The original output is kept; read the corrected text next to it with edited in the execution result. |
| `commandId`        | `string`   | —        | A value to identify resends (up to 128 characters)                                                                                                                                                                                                                                                                                                                                             |
| `contextVersion`   | `integer`  | —        | gate.contextVersion of the work item you read before deciding (an integer of 1 or more); omit it when gate.contextVersion is null. If the work item has changed since, 409 stale\_context. Required when you send editedOutput for a work item whose gate.contextVersion is not null.                                                                                                          |

- If you resend the same content with the same `commandId`, the result of the first request (`{ "decision": …, "alreadyDecided": true }`) is returned. Sending different content with the same `commandId` returns `409 Conflict` (`command_conflict`).
- Sending to a review request that has already been decided with a different `commandId` (or without `commandId`) returns `409 Conflict` (`already_decided`). Get the review request again and read the current decision.
- Send-backs are allowed up to the maximum number of send-backs to one step (`gate.sendBackLimit`).

For a decision sent with `contextVersion`, if the review request changed after you read it, `409 Conflict` (`stale_context`) is returned. Get the review request again, and send the new `gate.contextVersion`.

#### Request Example

**Decide work item**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "decision": "proceed",
  "reason": "The difference was between tax-included and tax-excluded amounts",
  "contextVersion": 1,
  "commandId": "decide-20261118-0001"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision",
  headers={"Authorization": f"Bearer {token}"},
  json={'decision': 'proceed', 'reason': 'The difference was between tax-included and tax-excluded amounts', 'contextVersion': 1, 'commandId': 'decide-20261118-0001'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"decision": "proceed", "reason": "The difference was between tax-included and tax-excluded amounts", "contextVersion": 1, "commandId": "decide-20261118-0001"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"decision": "proceed", "reason": "The difference was between tax-included and tax-excluded amounts", "contextVersion": 1, "commandId": "decide-20261118-0001"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type             | Description                                                                                          |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `decision`       | `string`         | Decision                                                                                             |
| `channel`        | `string \| null` | How it was decided ("api" when decided through the API). Not included in the response to a resend    |
| `alreadyDecided` | `boolean`        | Included as true only when a resend with the same commandId returned the result of the first request |

#### Response Example

```json
{
  "decision": "proceed",
  "channel": "api"
}
```

#### Error Responses

| Status | code                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`           | workItemId or sendBackToStepId is not a UUID, decision is missing or not one of the values above, commandId or destinationId is only whitespace, editedOutput is not a string, is blank, or is longer than 20000 characters without leading and trailing whitespace, contextVersion is not an integer of 1 or more, basisDigest was sent, or editedOutput was sent without contextVersion for a work item that has a version, or a field has the wrong type or length |
| `400`  | `invalid_parameter`           | sendBackFiles is not an array, has 6 or more items, or has an item that is not a UUID                                                                                                                                                                                                                                                                                                                                                                                 |
| `400`  | `invalid_send_back_files`     | A file in sendBackFiles is not in the project library or has been deleted                                                                                                                                                                                                                                                                                                                                                                                             |
| `400`  | `send_back_files_not_allowed` | sendBackFiles was sent with a decision other than send\_back, or for a connection confirmation                                                                                                                                                                                                                                                                                                                                                                        |
| `400`  | `invalid_body`                | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `400`  | `reason_required`             | reason is missing for "send\_back" or "reject"                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400`  | `invalid_send_back_step`      | sendBackToStepId is not a step that can be specified as the send-back step                                                                                                                                                                                                                                                                                                                                                                                            |
| `400`  | `destination_required`        | Tried to proceed a review request that has destinations without destinationId                                                                                                                                                                                                                                                                                                                                                                                         |
| `400`  | `invalid_destination`         | destinationId is not one of the destinations, or destinationId was sent with a decision other than "proceed"                                                                                                                                                                                                                                                                                                                                                          |
| `400`  | `invalid_decision`            | "send\_back" was sent for a connection confirmation (evidence.gateKind is "connection"). A connection confirmation accepts only "proceed" and "reject"                                                                                                                                                                                                                                                                                                                |
| `400`  | `edited_output_not_allowed`   | editedOutput was sent with a decision other than "proceed", or for a work item that cannot be corrected (a merge, a connection confirmation, a review raised by an agent step's result, and so on)                                                                                                                                                                                                                                                                    |
| `403`  | `insufficient_scope`          | The project:decide scope is missing                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `403`  | `forbidden`                   | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `403`  | `sso_required`                | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `403`  | `not_gate_owner`              | A member of the project who is not a reviewer                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `404`  | `workitem_not_found`          | The review request does not exist, or you cannot read it                                                                                                                                                                                                                                                                                                                                                                                                              |
| `409`  | `already_decided`             | It has already been decided                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `409`  | `command_conflict`            | Different content was sent with the same commandId                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `409`  | `invalid_state`               | It is not waiting for review (for example, it was cancelled)                                                                                                                                                                                                                                                                                                                                                                                                          |
| `409`  | `send_back_limit_exceeded`    | The maximum number of send-backs has been reached                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `409`  | `stale_context`               | The review request changed after you read it (the version sent is different from the current version)                                                                                                                                                                                                                                                                                                                                                                 |
| `413`  | `body_too_large`              | The body exceeds 3 MiB                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `415`  | `unsupported_media_type`      | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                                                                                                  |

### PATCH`/v1/workitems/{workItemId}`

Extends the due date (`expiresAt`) of a review request. Reviewers, their delegates during the delegation period, and owners and operators (including people with the organization operations role) can call this API. Extending it also clears the overdue flag (`overdue`).<!-- --> The due date of a connection confirmation (`evidence.gateKind` is `"connection"`) cannot be extended.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                              |
| ------------ | -------- | -- | ------------------------------- |
| `workItemId` | `string` | 必須 | ID of the review request (UUID) |

#### Request Body

| Field       | Type     | Required | Description                                        |
| ----------- | -------- | -------- | -------------------------------------------------- |
| `expiresAt` | `string` | Yes      | New due date (an ISO 8601 date-time in the future) |

Resending the same value gives the same result.

#### Request Example

**Extend work item**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "expiresAt": "2026-11-22T09:00:00.000Z"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
  headers={"Authorization": f"Bearer {token}"},
  json={'expiresAt': '2026-11-22T09:00:00.000Z'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"expiresAt": "2026-11-22T09:00:00.000Z"}),
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
payload := []byte(`{"expiresAt": "2026-11-22T09:00:00.000Z"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field               | Type             | Description                                                                                                                                                                                                                                                                          |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workitem`          | `object \| null` | The review request after the extension. The fields are the same as workitem in Get a Review Request. null when someone who cannot read the review request (an operator or a person with the organization operations role who is not a reviewer, a delegate, or an owner) extended it |
| `expiresAt`         | `string`         | The due date after the extension (ISO 8601)                                                                                                                                                                                                                                          |
| `previousExpiresAt` | `string \| null` | The due date before the extension (ISO 8601)                                                                                                                                                                                                                                         |

If the due date is extended and reading the review request back then fails for a reason other than not being able to read it (404), `502 Bad Gateway` (`upstream_connection_error`) is returned. The due date may already have been extended, so if you can read the review request, check `expiresAt` with Get a Review Request before resending.

#### Response Example

```json
{
  "workitem": {
    "workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
    "title": "Check invoices with differences",
    "status": "assigned",
    "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
    "decision": null,
    "requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "expiresAt": "2026-11-22T09:00:00.000Z",
    "gateMode": "blocking",
    "overdue": false,
    "decidedAt": null,
    "createdAt": "2026-11-18T01:34:40.000Z",
    "updatedAt": "2026-11-18T01:34:40.000Z",
    "canDecide": true,
    "description": "1 of the 12 invoices has an amount difference.",
    "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
    "runStepId": "rs:1843",
    "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "approverUserIds": [
      "f47ac10b-58cc-4372-a567-0e02b2c3d479"
    ],
    "overdueAction": "none",
    "evidence": {
      "summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
      "conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "files": [],
      "gateKind": "review",
      "stepName": "Amount check",
      "outcome": "completed",
      "executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
      "reasonCode": null,
      "escalateToUserId": null,
      "destinations": [],
      "connector": null,
      "service": null,
      "mode": null,
      "tool": null,
      "waitMinutes": null,
      "handoff": []
    },
    "decidedByKind": null,
    "decidedByRef": null,
    "decisionReason": null,
    "sendBackToStepId": null,
    "decisionResult": null
  },
  "expiresAt": "2026-11-22T09:00:00.000Z",
  "previousExpiresAt": "2026-11-20T09:00:00.000Z"
}
```

#### Error Responses

| Status | code                        | Description                                                                                                                                                                                                          |
| ------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`         | workItemId is not a UUID, or expiresAt is missing, is not an ISO 8601 date-time, or is not in the future                                                                                                             |
| `400`  | `invalid_body`              | The body is malformed JSON or not a JSON object                                                                                                                                                                      |
| `403`  | `insufficient_scope`        | The project:decide scope is missing                                                                                                                                                                                  |
| `403`  | `forbidden`                 | Called with a system integration token                                                                                                                                                                               |
| `403`  | `sso_required`              | The user does not sign in with SSO                                                                                                                                                                                   |
| `403`  | `not_gate_owner`            | A member of the project who is neither a reviewer, a delegate, an owner, nor an operator, and does not have the organization operations role                                                                         |
| `404`  | `workitem_not_found`        | The review request does not exist, or you are neither a reviewer, a delegate, a member of the project, nor a person with the organization operations role                                                            |
| `409`  | `already_decided`           | It has already been decided                                                                                                                                                                                          |
| `409`  | `invalid_state`             | It is not waiting for review (for example, it was cancelled), or it is a connection confirmation                                                                                                                     |
| `413`  | `body_too_large`            | The body exceeds 3 MiB                                                                                                                                                                                               |
| `415`  | `unsupported_media_type`    | The Content-Type of the body is not application/json                                                                                                                                                                 |
| `502`  | `upstream_connection_error` | The due date was extended, and reading the review request back failed for a reason other than not being able to read it (404) (if you can read the review request, check with Get a Review Request before resending) |

## Queue

The queue lists the things that need a person (overdue review requests, requests waiting for review, failed observations of external waits, workflow runs past their deadline or stalled, failed steps, steps waiting after a send-back, and failed sweeps), one row per item, in order of priority. It is the same as “Action needed” on the screen.

- The project queue (`GET /v1/projects/{projectId}/queue`) returns all rows of the project. Members of the project and people with the organization operations role can read it.
- Your queue (`GET /v1/queue`) returns the rows you are assigned to, across the projects you take part in. While you are someone's delegate, it also returns that person's review request rows.
- To act on a row, pass the ID it carries (not the row ID, `queueItemId`) to the following APIs.

| What to do                                     | API                                                            | ID to use     |
| ---------------------------------------------- | -------------------------------------------------------------- | ------------- |
| Proceed, send back, or reject a review request | `POST /v1/workitems/{workItemId}/decision`                     | `workItemId`  |
| Extend the due date of a review request        | `PATCH /v1/workitems/{workItemId}`                             | `workItemId`  |
| Change the deadline of a workflow run          | `PATCH /v1/projects/{projectId}/runs/{runId}`                  | `runId`       |
| Reassign the reviewers of a workflow run       | `PUT /v1/projects/{projectId}/runs/{runId}/approvers`          | `runId`       |
| Run a failed sweep again                       | `POST /v1/projects/{projectId}/executions/{executionId}/rerun` | `executionId` |

### Endpoint List

| メソッド | エンドポイント                          | 説明                                        | Scope (SaaS)   |
| ---- | -------------------------------- | ----------------------------------------- | -------------- |
| GET  | `/v1/projects/{projectId}/queue` | Get the queue of a project                | `project:read` |
| GET  | `/v1/queue`                      | Get the queue of rows you are assigned to | `project:read` |

### Kinds of Rows

The values of `kind` (the kind of row).

| Value                   | Shown on the screen | What it is                                                                     |
| ----------------------- | ------------------- | ------------------------------------------------------------------------------ |
| `gate_overdue`          | Overdue             | A review request past its due date                                             |
| `run_deadline_overdue`  | Past deadline (run) | A workflow run past its deadline                                               |
| `external_wait_blocked` | Waiting on external | A review request whose external wait cannot be observed                        |
| `gate_pending`          | Awaiting approval   | A review request waiting for review                                            |
| `run_stalled`           | Stalled             | A workflow run that has stopped moving                                         |
| `execution_failed`      | Failed              | A failed step                                                                  |
| `send_back_pending`     | Awaiting rework     | A step that was sent back and is waiting                                       |
| `sweep_failed`          | Sweep failed        | A failed sweep (sweeps stopped for a connection confirmation are not included) |

### GET`/v1/projects/{projectId}/queue`

Gets the queue of a project in order of priority. The order is priority, then due date, then the start point of the elapsed time, then the target ID (the part of the row ID after `:`), and cannot be changed. Supports cursor-based pagination.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |

#### Query Parameters

| Parameter | Type      | Default | Description                                                            |
| --------- | --------- | ------- | ---------------------------------------------------------------------- |
| `kind`    | `string`  | `—`     | Filter by kind of row (a value in "Kinds of Rows" above)               |
| `limit`   | `integer` | `50`    | Number of items per page (1-100)                                       |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response) |

#### Request Example

**List project queue**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue?kind=gate_pending&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "gate_pending", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue" + "?kind=gate_pending&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue?kind=gate_pending&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                               | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queueItems`                        | `array`           | Array of queue rows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `queueItems[].queueItemId`          | `string`          | Row ID, in the form `<target type>:<target ID>`. The target type is one of four: `workitem` (review request rows: `gate_overdue`, `external_wait_blocked`, `gate_pending`), `run_step` (failed steps and steps awaiting rework), `placement` (failed sweeps), and `run` (workflow runs past their deadline or stalled). It is not the kind of the row (`kind`): when a review request changes from `gate_pending` to `gate_overdue`, the ID stays the same. To tell rows apart, use the returned value as is; do not build or split it. To act on a row, use `workItemId`, `runId` or `executionId` |
| `queueItems[].kind`                 | `string`          | Kind of row (see "Kinds of Rows" above)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `queueItems[].priority`             | `number \| null`  | Priority (1 to 4; 1 is the highest)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `queueItems[].projectId`            | `string \| null`  | ID of the project                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `queueItems[].projectName`          | `string \| null`  | Name of the project                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `queueItems[].workItemId`           | `string \| null`  | ID of the review request. Only for review request rows (gate\_overdue, external\_wait\_blocked, gate\_pending); otherwise null. Can be used as is with the review request APIs                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `queueItems[].runId`                | `string \| null`  | ID of the workflow run. null when absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `queueItems[].stepId`               | `string \| null`  | ID of the step. null when absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `queueItems[].placementId`          | `string \| null`  | ID of the placement. null when absent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `queueItems[].executionId`          | `string \| null`  | ID of the execution. Can be used as is to get the execution result. rs:\<number> for a failed step (execution\_failed), the UUID of the sweep execution for a failed sweep (sweep\_failed), and the same value as the review material (evidence.executionId) for review request rows. Otherwise null                                                                                                                                                                                                                                                                                                |
| `queueItems[].stepName`             | `string \| null`  | Name of the step                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `queueItems[].agentName`            | `string \| null`  | Name of the Agent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `queueItems[].title`                | `string \| null`  | Title of the review request. Only for review request rows; otherwise null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `queueItems[].dueAt`                | `string \| null`  | Due date (ISO 8601): the due date of the review request or the deadline of the workflow run. Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `queueItems[].elapsedFrom`          | `string \| null`  | Start point for counting the elapsed time (ISO 8601). For review request rows, when the review request was created                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `queueItems[].assigneeUserIds`      | `array`           | User IDs of the assignees: the reviewers for review request rows, and the reviewers of the review that sent it back for rows waiting after a send-back (in both cases, people who are still members). The owners of the project for failed steps, failed sweeps, and workflow runs past their deadline or stalled. For review request rows returned to you as a delegate, these are still the reviewers, not you                                                                                                                                                                                    |
| `queueItems[].escalateToUserId`     | `string \| null`  | User ID of the contact when overdue. Only for review request rows; otherwise null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `queueItems[].cause`                | `object \| null`  | For rows that come from a failure, the result (outcome) and reason (reasonCode). Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `queueItems[].gateKind`             | `string \| null`  | Kind of review (same values as gateKind in the review material)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `queueItems[].observationErrorCode` | `string \| null`  | Reason the observation of the external wait failed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `queueItems[].sendBackLimitReached` | `boolean \| null` | Whether the maximum number of send-backs has been reached                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hasMore`                           | `boolean`         | Whether there is a next page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `cursor`                            | `string`          | Cursor for the next page. Included only when hasMore is true                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### Response Example

```json
{
  "queueItems": [
    {
      "queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
      "kind": "gate_pending",
      "priority": 3,
      "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
      "projectName": "Invoice reconciliation",
      "workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
      "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "executionId": null,
      "stepName": "Difference check",
      "agentName": "Accounting Agent",
      "title": "Check invoices with differences",
      "dueAt": "2026-11-20T09:00:00.000Z",
      "elapsedFrom": "2026-11-18T01:30:00.000Z",
      "assigneeUserIds": [
        "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      ],
      "escalateToUserId": null,
      "cause": null,
      "gateKind": "review",
      "observationErrorCode": null,
      "sendBackLimitReached": false
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                                                 |
| ------ | -------------------- | ------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | projectId is not a UUID, kind is not one of the values above, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                                           |
| `403`  | `forbidden`          | Called with a system integration token                                                      |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                          |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                         |

### GET`/v1/queue`

Gets the rows you are assigned to, across the projects you take part in, and the review requests you can decide as an active delegate, in order of priority. Delegate rows can come from projects you are not a member of; you can read, decide, and extend those review requests with `workItemId`. The query parameters, response fields, and order are the same as the project queue.

#### Request Example

**List my queue**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue?kind=gate_pending&limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue",
  headers={"Authorization": f"Bearer {token}"},
  params={"kind": "gate_pending", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue" + "?kind=gate_pending&limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/queue?kind=gate_pending&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Example

```json
{
  "queueItems": [
    {
      "queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
      "kind": "gate_pending",
      "priority": 3,
      "projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
      "projectName": "Invoice reconciliation",
      "workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
      "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
      "stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "executionId": null,
      "stepName": "Difference check",
      "agentName": "Accounting Agent",
      "title": "Check invoices with differences",
      "dueAt": "2026-11-20T09:00:00.000Z",
      "elapsedFrom": "2026-11-18T01:30:00.000Z",
      "assigneeUserIds": [
        "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      ],
      "escalateToUserId": null,
      "cause": null,
      "gateKind": "review",
      "observationErrorCode": null,
      "sendBackLimitReached": false
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                 | Description                                                        |
| ------ | -------------------- | ------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | kind is not one of the values above, or limit or cursor is invalid |
| `403`  | `insufficient_scope` | The project:read scope is missing                                  |
| `403`  | `forbidden`          | Called with a system integration token                             |
| `403`  | `sso_required`       | The user does not sign in with SSO                                 |

## Connectors

Reads the MCP servers and A2A agents used by project executions. Only the information the other side publishes (tool names and descriptions, and the agent card) is returned. Endpoint URLs and credentials are not returned.

- You can find the connector ID (`connectionId`) in `connectors[].connectionId` of Get Project and in `operations[].connectionId` of the list of tool calls.
- Any user of the tenant can read any connector (even without being a member of the project). However, an MCP connector that is limited to certain organizations or job types in the admin console returns `404 Not Found` (`connector_not_found`) to people who cannot use it. With `projectId`, this is decided by the organization and job type of the project's owner, as on the project's screen (without it, by those of the caller; when the caller is a system administrator, this limit does not apply and the connector can be read through this API). A connector that was disabled or deleted in the admin console also returns `404 Not Found` (`connector_not_found`).
- Sign-in to a connector is done on the project screen.

### Endpoint List

| メソッド | エンドポイント                             | 説明                   | Scope (SaaS)   |
| ---- | ----------------------------------- | -------------------- | -------------- |
| GET  | `/v1/connectors/mcp/{connectionId}` | Get an MCP connector | `project:read` |
| GET  | `/v1/connectors/a2a/{connectionId}` | Get an A2A connector | `project:read` |

### GET`/v1/connectors/mcp/{connectionId}`

Gets an MCP connector and its list of tools. The list of tools is the one fetched from the MCP server and saved in the admin console.

#### Path Parameters

| パラメータ          | 型        | 必須 | 説明                                                   |
| -------------- | -------- | -- | ---------------------------------------------------- |
| `connectionId` | `string` | 必須 | Connector ID (a positive integer of up to 16 digits) |

#### Query Parameters

| パラメータ       | 型        | 必須 | 説明                                                                                                                                                                                                                                                             |
| ----------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId` | `string` | —  | The ID (UUID) of the project that uses the connector. With it, whether the connector can be used is decided by the organization and job type of the project's owner. Only members of the project and people with the organization operations role can pass it. |

#### Request Example

**Get MCP connector**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/mcp/12",
  headers={"Authorization": f"Bearer {token}"},
  params={"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/mcp/12" + "?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                         | Type              | Description                                                                                                                                               |
| ----------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`                        | `string`          | "mcp"                                                                                                                                                     |
| `connectionId`                | `string`          | Connector ID                                                                                                                                              |
| `name`                        | `string \| null`  | Connector name                                                                                                                                            |
| `requiresLogin`               | `boolean`         | Whether you must sign in on the project screen before using the connector                                                                                 |
| `tools`                       | `array`           | Array of tools                                                                                                                                            |
| `tools[].name`                | `string \| null`  | Tool name                                                                                                                                                 |
| `tools[].displayName`         | `string \| null`  | Display name                                                                                                                                              |
| `tools[].description`         | `string \| null`  | Description                                                                                                                                               |
| `tools[].inputSchema`         | `object \| null`  | Input schema of the tool (as declared by the MCP server). null until the list of tools is fetched again in the admin console                              |
| `tools[].outputSchema`        | `object \| null`  | Output schema of the tool (as declared by the MCP server). null if not declared                                                                           |
| `tools[].declaredAnnotations` | `object \| null`  | Tool annotations (such as readOnlyHint, as self-declared by the MCP server). This product does not verify them and does not use them to control execution |
| `tools[].presentInLastFetch`  | `boolean \| null` | Whether it was also there the last time the list was fetched (false means the tool is gone from the MCP server)                                           |
| `toolsFetchedAt`              | `string \| null`  | When the list of tools was last fetched (ISO 8601). Set even when the fetch returned 0 tools. null if it has never been fetched                           |

#### Response Example

```json
{
  "kind": "mcp",
  "connectionId": "12",
  "name": "Internal document search",
  "requiresLogin": false,
  "tools": [
    {
      "name": "search_documents",
      "displayName": "Document search",
      "description": "Searches internal documents by keyword",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ]
      },
      "outputSchema": null,
      "declaredAnnotations": {
        "readOnlyHint": true
      },
      "presentInLastFetch": true
    }
  ],
  "toolsFetchedAt": "2026-11-17T09:30:00.000Z"
}
```

#### Error Responses

| Status | code                  | Description                                                                                                              |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`   | connectionId is not a positive integer of up to 16 digits, or projectId is not a UUID                                    |
| `403`  | `insufficient_scope`  | The project:read scope is missing                                                                                        |
| `403`  | `forbidden`           | Called with a system integration token                                                                                   |
| `403`  | `sso_required`        | With projectId, the user does not sign in with SSO                                                                       |
| `404`  | `connector_not_found` | The connector does not exist, is disabled, or cannot be used by the organization and job type                            |
| `404`  | `project_not_found`   | The project in projectId does not exist, or you are not a member of it or a person with the organization operations role |

### GET`/v1/connectors/a2a/{connectionId}`

Gets an A2A connector and its agent card. The agent card is the one saved in the admin console.

#### Path Parameters

| パラメータ          | 型        | 必須 | 説明                                                   |
| -------------- | -------- | -- | ---------------------------------------------------- |
| `connectionId` | `string` | 必須 | Connector ID (a positive integer of up to 16 digits) |

#### Request Example

**Get A2A connector**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

const data = await response.json();
console.log(data);
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/connectors/a2a/7", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                            | Type             | Description                                                               |
| -------------------------------- | ---------------- | ------------------------------------------------------------------------- |
| `kind`                           | `string`         | "a2a"                                                                     |
| `connectionId`                   | `string`         | Connector ID                                                              |
| `name`                           | `string \| null` | Connector name                                                            |
| `requiresLogin`                  | `boolean`        | Whether you must sign in on the project screen before using the connector |
| `agentCard`                      | `object`         | Agent card                                                                |
| `agentCard.description`          | `string \| null` | Description                                                               |
| `agentCard.version`              | `string \| null` | Version                                                                   |
| `agentCard.provider`             | `object \| null` | Provider                                                                  |
| `agentCard.skills`               | `array`          | Skills                                                                    |
| `agentCard.capabilities`         | `object \| null` | Supported capabilities                                                    |
| `agentCard.defaultInputModes`    | `array`          | Accepted formats                                                          |
| `agentCard.defaultOutputModes`   | `array`          | Returned formats                                                          |
| `agentCard.supportedInterfaces`  | `array`          | Supported connection methods                                              |
| `agentCard.documentationUrl`     | `string \| null` | Documentation URL                                                         |
| `agentCard.iconUrl`              | `string \| null` | Icon URL                                                                  |
| `agentCard.securitySchemes`      | `object \| null` | How to authenticate to the agent (as the agent publishes it)              |
| `agentCard.securityRequirements` | `array`          | Authentication requirements (as the agent publishes them)                 |

The contents of `provider`, `skills`, `capabilities`, and `supportedInterfaces` in `agentCard` are in the form the other agent publishes.

#### Response Example

```json
{
  "kind": "a2a",
  "connectionId": "7",
  "name": "Translation Agent",
  "requiresLogin": false,
  "agentCard": {
    "description": "Translates documents into the specified language",
    "version": "1.0.0",
    "provider": {
      "organization": "Example Corp.",
      "url": "https://example.com"
    },
    "skills": [
      {
        "id": "translate",
        "name": "Translation",
        "description": "Translates documents",
        "tags": [
          "translation"
        ]
      }
    ],
    "capabilities": {
      "streaming": true
    },
    "defaultInputModes": [
      "text/plain"
    ],
    "defaultOutputModes": [
      "text/plain"
    ],
    "supportedInterfaces": [
      {
        "url": "https://agent.example.com/a2a",
        "protocolBinding": "JSONRPC",
        "protocolVersion": "1.0"
      }
    ],
    "documentationUrl": null,
    "iconUrl": null,
    "securitySchemes": null,
    "securityRequirements": []
  }
}
```

#### Error Responses

| Status | code                  | Description                                               |
| ------ | --------------------- | --------------------------------------------------------- |
| `400`  | `invalid_parameter`   | connectionId is not a positive integer of up to 16 digits |
| `403`  | `insufficient_scope`  | The project:read scope is missing                         |
| `403`  | `forbidden`           | Called with a system integration token                    |
| `404`  | `connector_not_found` | The connector does not exist or is disabled               |

## Execution Conversations

Read the conversation with the Agent during an execution (the request to the Agent, explanations along the way, the final response, and so on) with `GET /v1/conversations/{conversationId}/messages` of the conversation API<!-- --> (the `chat:history` scope)<!-- -->. For details, see [Conversation Management in the User API Reference (Conversations, Library, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#conversations).

- You can find `conversationId` in `conversationId` of the execution history and the execution result.
- Only the owner of the project at the time of the execution (the person the execution runs as) can read it, because project executions run in the owner's name. Conversations of executions from before the ownership was transferred are read by the previous owner (see [Who decides what](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/roles.md)). Other owners, operators and members get `404 Not Found`. It cannot be read from a system integration.
- An execution of a workflow step, and an execution of a cycle started by a webhook or an email, each have one conversation. For periodic sweeps
  <!-- -->
  of a cycle, the messages of each round are added to one conversation per placement and step. Because the conversation API does not link messages to executions, identify them by the messages whose `sender` is `"User"` (the request to the Agent for that round) around the start time of the execution (`startedAt`).

## Error Responses

### HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

| Status                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | Invalid request parameters                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `401 Unauthorized`           | Token is invalid or missing. Also returned for a token of a user whose use was suspended by an administrator (see "Suspended users" below)                                                                                                                                                                                                                                                                                                               |
| `403 Forbidden`              | No access permission to the resource. Also returned when an administrator restricts where the public API can be called from and the IP address of the caller is not in the allowed list (`error.code` is `ip_not_allowed`)                                                                                                                                                                                                                               |
| `404 Not Found`              | Resource does not exist, or the path or method is not defined (405 is not returned)                                                                                                                                                                                                                                                                                                                                                                      |
| `409 Conflict`               | Operation conflict, such as the resource currently being processed                                                                                                                                                                                                                                                                                                                                                                                       |
| `409 Conflict`               | A person with the organization operations role (the "Operator" role assigned in "Admin Roles" in the admin console) who does not take part in the project called an operation that role cannot use (`error.code` is `forbidden_role`). It does not clear by waiting. For an owner-only operation, ask an owner of the project to do it. For other operations, ask an owner to add you to the project; you can then call them as your project role allows |
| `413 Payload Too Large`      | Request body exceeds the size limit                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `415 Unsupported Media Type` | The request body format (Content-Type) is not supported                                                                                                                                                                                                                                                                                                                                                                                                  |
| `429 Too Many Requests`      | Rate limit or concurrent-run limit exceeded. `error.type` is `rate_limit_error`, and `error.code` depends on the endpoint (for example `monthly_quota_exceeded` for the monthly limit and `too_many_active_runs` for concurrent project runs). Please wait and retry.                                                                                                                                                                                    |
| `500 Internal Server Error`  | Internal server error                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `502 Bad Gateway`            | Communication error with upstream services (authentication / chat backends, etc.)                                                                                                                                                                                                                                                                                                                                                                        |
| `503 Service Unavailable`    | Service temporarily unavailable                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `504 Gateway Timeout`        | Upstream service response timeout                                                                                                                                                                                                                                                                                                                                                                                                                        |

### Error Response Format

All error responses are returned in the following common structure.

| Field                    | Type     | Description                                                                                                                                                                                                                                                        |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `error.type`             | `string` | Error classification. One of: "invalid\_request\_error", "authentication\_error", "insufficient\_scope\_error", "forbidden\_error", "not\_found\_error", "conflict\_error", "payload\_too\_large\_error", "rate\_limit\_error", "server\_error", "upstream\_error" |
| `error.message`          | `string` | Human-readable error message                                                                                                                                                                                                                                       |
| `error.code`             | `string` | Machine-processable error code (e.g., "missing\_parameter", "invalid\_parameter", "invalid\_token")                                                                                                                                                                |
| `error.param`            | `string` | The parameter that caused the error. Included only for validation errors                                                                                                                                                                                           |
| `error.reason`           | `string` | The kind of reason for the refusal. Included only for 409 (definition\_invalid) of the project APIs                                                                                                                                                                |
| `error.suggested_action` | `string` | Recommended action to take. Included only for some errors                                                                                                                                                                                                          |

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid parameter: limit",
    "code": "invalid_parameter",
    "param": "limit",
    "suggested_action": "limit must be between 1 and 100"
  }
}
```

### Suspended users

A call with the token of a user whose use was suspended by an administrator returns `401 Unauthorized`. `error.code` is `account_suspended`.

The following APIs do not check whether the user is suspended: `GET /v1/organizations`, `GET /v1/job-types`, `GET /v1/personas`, `GET /v1/user`, `PATCH /v1/user`, and the MCP tools `list_personas` and `cancel_chat` (when no task is in progress). They can still be called after the suspension until the access token expires. A suspended user cannot refresh the access token.

### When the Request Is Stopped Before Reaching the API

If a layer in front of the API (such as a security inspection) returns an HTML error page, the response is replaced with JSON in the common format above. In that case, `error.code` is one of the following.

| Status                     | error.code           | Description                                                                                                                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403                        | `waf_blocked`        | The request was stopped by a security inspection in front of the API. If the request is legitimate, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |
| 4xx and 5xx other than 403 | `upstream_api_error` | The request was rejected by, or caused an error in, a layer in front of the API. If this continues, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |

| Field             | Type     | Description                                                                                                                            |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `error.reference` | `string` | Reference number for a request stopped before reaching the API. Include it when contacting support. Omitted when no value is available |

```json
{
  "error": {
    "type": "forbidden_error",
    "message": "The request was blocked by a web application firewall before it reached the API.",
    "code": "waf_blocked",
    "suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
    "reference": "20261018T012345Z-0123456789abcdef"
  }
}
```
