# User API Reference (Projects)

This is the reference for the Marketplace user-facing APIs that handle projects. With an application (sign-in from an external tool) token, you can create and configure projects, place registered Agents, start workflow runs, check the results and artifacts of executions, and decide review requests. For the conversation and organization APIs, see [User API Reference (Conversations, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-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/marketplace/api/guide/project-api-guide.md).

A system integration token can call only four project APIs: list projects, start a workflow run, fire a trigger, and get a workflow run ([System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md#projects)). 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 base URL below. Replace `<your-domain>` with the domain of your environment.

Marketplace

`https://<your-domain>/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 missing or invalid, `401 Unauthorized` is returned. The Marketplace edition applies no scope restrictions.

Call the APIs on this page with a user token obtained through an application (sign-in from an external tool). Sign-in from an external tool is available only in environments where an administrator has opened its entrance ([API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md)). Calling them with a user token obtained in any other way (such as the token used when signing in to the Main Screen) returns `404 Not Found` for every endpoint. For how to obtain a token, see the [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md) and the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md).

## Common Rules

These rules apply to the APIs on this page.

### Who Can Call and 404 / 403

- APIs that read a project and what it contains (steps, placements, executions, and so on) can be called by members of the project. Except for creating a project, APIs that write (including starting a workflow run and firing a trigger) can be called only by owners of the project. Who can call the review request, queue, and connector APIs is described in their sections. A member who is not an owner gets `403 Forbidden` (`owner_only`).
- A project you are not a member of and a project that does not exist both return `404 Not Found`, and the response does not tell them apart. However, you can read the structure of a shared project with Get Project (`GET /v1/projects/{projectId}`) even if you are not a member.
- Each endpoint has one code for `404 Not Found`, named after the last resource in the path (for example, `placement_not_found` for the placement APIs and `execution_not_found` for the execution APIs). Endpoints without a resource ID in the path use `project_not_found`. When the project is not visible, the endpoint's code is still returned.
- When an ID specified in the body (a registered Agent, a step, a user, and so on) does not exist or is not visible, the response differs by endpoint (for example, `marketplaceAgentId` of a placement returns `400 Bad Request` (`agent_not_found`), and `stepIds` of a placement returns `400 Bad Request` (`invalid_parameter`)). See the description and error responses of each endpoint.
- When a query that filters a list (`placement_id`, `step_id`, or `run_id`) specifies an ID that does not exist, an empty list is returned.
- Query names are in snake\_case (`my_role`, `placement_id`, `step_id`, `run_id`, `project_id`). The earlier names (`myRole`, `placementId`, `stepId`, `runId`, `projectId`) are also accepted. Giving different values to both names returns `400 Bad Request` (`invalid_parameter`).
- For a token of a user whose user record is not linked to an account of the authorization server, the project, review request, and queue APIs (except list projects, start a workflow run, fire a trigger, and get a workflow run) return `403 Forbidden` (`sso_required`). Signing in to the Main Screen once links them.

### Request Handling

- Query parameters and body fields not in the specification are ignored. An invalid value for a query parameter in the specification, or a `cursor` that cannot be read, returns `400 Bad Request`.
- Send the body as a JSON object. A `Content-Type` other than `application/json` returns `415 Unsupported Media Type` (`unsupported_media_type`), and malformed JSON or a body that is not a JSON object returns `400 Bad Request` (`invalid_body`).
- The body can be up to 16 KiB (3 MiB for the API that creates a project and the APIs that decide a review request or extend its due date). A larger body returns `413 Payload Too Large` (`body_too_large`).
- Fields that this API deliberately does not accept return `400 Bad Request` (`invalid_parameter`) when sent, because silently ignoring them would make a change look applied when it is not. Each endpoint lists these fields.

### Editing and Resending

- APIs that edit take the `digest` returned by the get API as `baseDigest`. If another change was made after you got it, `409 Conflict` (`stale_base`) is returned. Get it again and resend. Two edits that arrive at almost the same time may both succeed.
- The `digest` in the response is the value after the edit. You can use it for the next edit.
- Extending the due date of a review request, and changing the deadline or reassigning the reviewers of a workflow run, do not use `baseDigest` (they are not compared with changes made after you got the resource).
- The APIs that create projects and steps create another one when resent. If you did not receive a response, check with the project list or Get Project whether it was created before resending. The API that places a registered Agent returns the existing placement when resent with the same registered Agent and the same steps.
- Resends are identified by the `Idempotency-Key` header (required) for starting a workflow run, by `eventId` in the body for firing a trigger, and by `commandId` in the body for deciding a review request and reassigning reviewers. Resending with the same key returns the result of the first request.

### 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

List APIs read the next page with `limit` (1 to 100; 50 if omitted) and `cursor` (send the value from the previous response as is). `cursor` is returned only when `hasMore` is `true`. The number of items (total) is not returned. Lists with a different range or default for `limit`, lists without `limit`, lists that return all items, and lists whose `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

| メソッド   | エンドポイント                            | 説明                                             |
| ------ | ---------------------------------- | ---------------------------------------------- |
| GET    | `/v1/projects`                     | List the projects you participate in           |
| GET    | `/v1/projects/shared`              | List shared projects                           |
| GET    | `/v1/projects/organizations`       | Get the organizations you can set on a project |
| GET    | `/v1/projects/{projectId}`         | Get a project                                  |
| POST   | `/v1/projects`                     | Create a project                               |
| PATCH  | `/v1/projects/{projectId}`         | Edit a project                                 |
| DELETE | `/v1/projects/{projectId}`         | Delete a project                               |
| GET    | `/v1/projects/{projectId}/control` | Get the control settings                       |

### GET`/v1/projects`

Retrieves the list of projects you can access. 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`  | `—`     | Either "owner" 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" / "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.

<!-- -->

#### 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" or "archived"                                     |
| `projects[].tags`      | `array`   | Array of tags. An empty array when none are set                                            |
| `projects[].myRole`    | `string`  | The caller's own role in that project. Either "owner" 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) |

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

Lists shared projects (your own projects are included if they are shared). 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       |

#### 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", or "archived"                     |
| `projects[].tags`           | `array`          | Array of tags                                                |
| `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.

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | An invalid value for limit, cursor, type, tag, q, or sort               |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |

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

#### 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                                                      |

#### Error Responses

| Status | code                       | Description                                                                         |
| ------ | -------------------------- | ----------------------------------------------------------------------------------- |
| `403`  | `forbidden`                | Called with a system integration token                                              |
| `403`  | `sso_required`             | The user record is not linked to an account of the authorization server             |
| `503`  | `organization_unavailable` | The organization the user belongs to cannot be confirmed (resend the request later) |

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

#### Path Parameters

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

#### 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" 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 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)                                                                                                                                                                    |
| `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.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}). null for a connector disabled or deleted on the admin screen, 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`  | The setting for whether a person is asked to confirm before this connector is used: "none", "first\_per\_execution", or "always". Set it 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), or "not\_connected" (not signed in). null when the status cannot be confirmed. Sign in on the screen                                   |
| `connectors[].createdAt`           | `string \| null`  | Registration time (ISO 8601)                                                                                                                                                                                             |

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), or "archived" (archived)                                                         |
| `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`  | Always null                                                                                                                   |
| `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                                                                                                          |
| `copyCount`                  | `number \| null`  | Number of times copied                                                                                                        |
| `ownerUserId`                | `string \| null`  | User ID of the owner                                                                                                          |
| `myRole`                     | `string \| null`  | Role of the calling user: "owner" or "member". null in a preview                                                              |
| `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                                                                      |

<!-- -->

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 |
| `unsupported_runtime` | An Agent of a kind this service cannot run is placed      |
| `unexpected_error`    | An unexpected failure                                     |

When a user who is not a member reads a shared project (a preview), `project` (without `organizationName` and `digest`; `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`, and `connectors` are not returned.

<!-- -->

#### Error Responses

| Status | code                | Description                                                                                   |
| ------ | ------------------- | --------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID                                                                       |
| `403`  | `forbidden`         | Called with a system integration token                                                        |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                       |
| `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 |

### POST`/v1/projects`

Creates a project. The user who creates it becomes the owner and the principal that runs the project. <!-- -->Choose an Agent from the Agent candidates (`GET /v1/projects/agent-candidates`), and then place it<!-- --> 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 ("workflow" in environments where cycle is not available)                                                                                                                             |
| `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). 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`         | —        | "ai" (run by an Agent) or "gate" (review step). "ai" if omitted. Only "ai" for cycle. null cannot be sent                                                                                                                       |

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

#### Response (201 Created)

| Field     | Type     | Description                                                                                              |
| --------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `project` | `object` | The created project. Same fields as project in Get Project (without organizationName; myRole is "owner") |
| `steps`   | `array`  | Array of the created steps. See "Step Fields" for the fields of an item                                  |

#### 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 trigger, policy, agents, guardrail, or templateRef was sent |
| `400`  | `invalid_body`             | The body is malformed JSON or not a JSON object                                                                                                                                                                           |
| `400`  | `cycle_disabled`           | cycle is not available in this environment                                                                                                                                                                                |
| `400`  | `cycle_gate_not_allowed`   | A review step ("gate") was specified for a cycle                                                                                                                                                                          |
| `400`  | `organization_not_member`  | An organization that cannot be set was specified                                                                                                                                                                          |
| `403`  | `forbidden`                | Called with a system integration token                                                                                                                                                                                    |
| `403`  | `sso_required`             | The user record is not linked to an account of the authorization server                                                                                                                                                   |
| `409`  | `project_limit_reached`    | The number of projects has reached the limit (in the Marketplace edition, 5 per environment; archived projects are not counted; 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                                                                                                                                                                  |

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

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

#### 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                                                                                                                                                                                                                                                                                                                                                                                              |
| `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                                                                                                                                                                                                                                                                                                                         |
| `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` (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<!-- --> 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.

<!-- -->

#### Response (200 OK)

| Field     | Type     | Description                                                                                  |
| --------- | -------- | -------------------------------------------------------------------------------------------- |
| `project` | `object` | The project after the edit. Same fields as project in Get Project (without organizationName) |

#### 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`  | `organization_not_member`  | An organization that cannot be set was specified                                                                                                                                                                                                                                                                                                                                     |
| `403`  | `forbidden`                | Called with a system integration token                                                                                                                                                                                                                                                                                                                                               |
| `403`  | `owner_only`               | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                         |
| `403`  | `sso_required`             | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                                                                                                              |
| `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                                                                                                                                                                                                                                                                                                                                             |
| `409`  | `organization_locked`      | An organization is already set (a different value or null was sent)                                                                                                                                                                                                                                                                                                                  |
| `409`  | `project_limit_reached`    | Tried to move the project out of "archived", but the number of projects has reached the limit (in the Marketplace edition, 5 per environment; the numbers are in error.message)                                                                                                                                                                                                      |
| `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                                                                                                                                                                                                                                                                                                                             |

### 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) |

#### Response (200 OK)

```json
{
  "projectId": "6addd341-cd6d-4061-b8dc-4e9a6669a720",
  "deleted": true
}
```

Calling it again returns `404 Not Found`.

#### Error Responses

| Status | code                | Description                                                                      |
| ------ | ------------------- | -------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID                                                          |
| `403`  | `forbidden`         | Called with a system integration token                                           |
| `403`  | `owner_only`        | A member who is not an owner                                                     |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server          |
| `404`  | `project_not_found` | The project does not exist, you are not a member, or it has already been deleted |

### 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) |

#### 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 on the admin screen), "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`         | "blocking" (wait for the reviewer's decision). "notify\_only" saved in an earlier version may be returned, but workflow runs always wait for the reviewer's decision regardless of the value                                                                                                                          |
| `gates[].overdueAction`   | `string`         | "none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting). A value saved in an earlier version may be returned, but in workflow runs nothing is decided automatically after the deadline regardless of the value; the reviewers are notified and it keeps waiting |
| `gates[].approverUserIds` | `array`          | Array of user IDs of the reviewers                                                                                                                                                                                                                                                                                    |
| `gates[].deadlineHours`   | `number \| null` | Deadline (hours)                                                                                                                                                                                                                                                                                                      |
| `operationClasses`        | `null`           | Not used at present (always null)                                                                                                                                                                                                                                                                                     |

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID                                                 |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |
| `404`  | `project_not_found` | The project does not exist, or you are not a member                     |

## 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"`). 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

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

### 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`  | "ai" (run by an Agent) or "gate" (review step)                                                                           |
| `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) or "closed\_failed" (close as failed)       |
| `onDegraded`         | `string \| null`  | What happens "when the Agent reports a failure": "gate" (request a review) or "proceed" (proceed as is)                  |
| `outcomeRoutes`      | `object \| null`  | Always null (outcome routes cannot be set in the Marketplace edition)                                                    |
| `laneId`             | `string \| null`  | Always null                                                                                                              |
| `placementExecution` | `string \| null`  | Always null (runs them one at a time in placement order)                                                                 |
| `digest`             | `string`          | The value to send as baseDigest when editing the step                                                                    |

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. Only "blocking" (wait for the reviewer's decision) can be sent ("notify\_only" returns 400 structure\_not\_for\_marketplace). "notify\_only" saved in an earlier version may be returned, but workflow runs always wait for the reviewer's decision regardless of the value                                                                                                                                                                           |
| `overdueAction`    | `string \| null` | After the deadline. You can send "none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting) or null (works as "none") ("proceed", "send\_back", and "reject" return 400 structure\_not\_for\_marketplace). A value saved in an earlier version may be returned, but in workflow runs nothing is decided automatically after the deadline regardless of the value; the reviewers are notified and it keeps waiting |
| `escalateToUserId` | `string \| null` | User ID of the contact when the deadline passes (a project member)                                                                                                                                                                                                                                                                                                                                                                                                   |
| `destinations`     | `array`          | Never included (destinations cannot be set in the Marketplace edition)                                                                                                                                                                                                                                                                                                                                                                                               |

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) |
| "gate" for onDenied and onDegraded                                                 | Can be set | 400 (cycle\_gate\_not\_allowed) |
| 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`         | —        | "ai" or "gate". "ai" if omitted. null or an empty string cannot be sent                                                                                                                                     |
| `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). null means no settings                                                                                                                  |

<!-- -->

#### 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 |

#### 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`  | `structure_not_for_marketplace` | A review step setting that the Marketplace edition does not have was sent ("notify\_only" or automatic processing after the deadline)                                                                                                                                                                             |
| `400`  | `step_reference_on_create`      | destinations was sent in gateConfig (including null or an empty array; destinations cannot be set in the Marketplace edition)                                                                                                                                                                                     |
| `400`  | `cycle_gate_not_allowed`        | Tried to add a review step to a cycle                                                                                                                                                                                                                                                                             |
| `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`  | `forbidden`                     | Called with a system integration token                                                                                                                                                                                                                                                                            |
| `403`  | `owner_only`                    | A member who is not an owner                                                                                                                                                                                                                                                                                      |
| `403`  | `sso_required`                  | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                                           |
| `404`  | `project_not_found`             | The project does not exist, or you are not a member                                                                                                                                                                                                                                                               |
| `409`  | `too_many_steps`                | There are already 12 steps                                                                                                                                                                                                                                                                                        |
| `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}/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`         | —        | "ai" or "gate"                                                                                                                                                                                                                                                                                                                                                               |
| `enabled`        | `boolean`        | —        | Whether it is enabled                                                                                                                                                                                                                                                                                                                                                        |
| `gateConfig`     | `object \| null` | —        | Settings of a review step. Only the fields you send are overlaid on the current values. null removes the settings. For a step that saved "notify\_only" or automatic processing after the deadline in an earlier version, sending only other fields returns 400 (structure\_not\_for\_marketplace). In that case, also send "blocking" for mode and "none" for overdueAction |
| `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" or "closed\_failed"                                                                                                                                                                                                                                                                                                                                                   |
| `onDegraded`     | `string \| null` | —        | "gate" or "proceed"                                                                                                                                                                                                                                                                                                                                                          |
| `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.

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

#### Response (200 OK)

| Field  | Type     | Description                                 |
| ------ | -------- | ------------------------------------------- |
| `step` | `object` | The step after the edit (with a new digest) |

#### 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`  | `structure_not_for_marketplace` | A step structure that the Marketplace edition does not have was sent (outcome routes, destinations, "notify\_only", automatic processing after the deadline, and so on)                                                                                                                                                                                                                                                                            |
| `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`  | `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_outcome_route`         | "goto" was specified (outcome routes cannot be set in the Marketplace edition, so "goto" cannot be used)                                                                                                                                                                                                                                                                                                                                           |
| `403`  | `forbidden`                     | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                             |
| `403`  | `owner_only`                    | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `sso_required`                  | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                                                                                                                                                                            |
| `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                                                                                                                                                                                                                                                                                                                                                                                                              |
| `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}/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) |

#### Response (200 OK)

| Field         | Type     | Description                                           |
| ------------- | -------- | ----------------------------------------------------- |
| `steps`       | `array`  | All steps after reordering                            |
| `stepsDigest` | `string` | The value for the order of the steps after reordering |

#### 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`  | `forbidden`              | Called with a system integration token                                                                           |
| `403`  | `owner_only`             | A member who is not an owner                                                                                     |
| `403`  | `sso_required`           | The user record is not linked to an account of the authorization server                                          |
| `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                                                              |
| `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}/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).

#### Path Parameters

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

#### Response (200 OK)

| Field         | Type      | Description                                             |
| ------------- | --------- | ------------------------------------------------------- |
| `stepId`      | `string`  | ID of the deleted step                                  |
| `deleted`     | `boolean` | Always true                                             |
| `historyKept` | `boolean` | Whether the step was kept for the records               |
| `steps`       | `array`   | All steps after the deletion                            |
| `stepsDigest` | `string`  | The value for the order of the steps after the deletion |

#### Error Responses

| Status | code                | Description                                                                   |
| ------ | ------------------- | ----------------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId or stepId is not a UUID                                             |
| `403`  | `forbidden`         | Called with a system integration token                                        |
| `403`  | `owner_only`        | A member who is not an owner                                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server       |
| `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) |

## Placements

A placement is <!-- -->a registered Agent (an Agent registered by an administrator)<!-- --> 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.

### Endpoint List

| メソッド   | エンドポイント                                                      | 説明                                                           |
| ------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| GET    | `/v1/projects/{projectId}/placements`                        | List placements                                              |
| GET    | `/v1/projects/{projectId}/placements/{placementId}`          | Get a placement                                              |
| GET    | `/v1/projects/agent-candidates`                              | List the registered Agents that can be placed                |
| POST   | `/v1/projects/{projectId}/placements`                        | Place an Agent                                               |
| DELETE | `/v1/projects/{projectId}/placements/{placementId}`          | Remove a placement                                           |
| PUT    | `/v1/projects/{projectId}/placements/{placementId}/steps`    | Change the steps of a placement                              |
| PATCH  | `/v1/projects/{projectId}/placements/{placementId}/schedule` | Stop, resume, or change the interval of a sweep (cycle only) |

### 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                                                                                                                                                                            |
| `displayOrder`           | `number \| null`  | Display order                                                                                                                                                                                     |
| `name`                   | `string \| null`  | Agent name                                                                                                                                                                                        |
| `description`            | `string \| null`  | Agent description                                                                                                                                                                                 |
| `goal`                   | `string \| null`  | Always null                                                                                                                                                                                       |
| `guardrail`              | `string \| null`  | Always null                                                                                                                                                                                       |
| `skills`                 | `array`           | Always an empty array                                                                                                                                                                             |
| `skillCount`             | `number \| null`  | Always 0                                                                                                                                                                                          |
| `playbookId`             | `string \| null`  | Always null                                                                                                                                                                                       |
| `playbookName`           | `string \| null`  | Always null                                                                                                                                                                                       |
| `inputFiles`             | `array`           | Always an empty array                                                                                                                                                                             |
| `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                                                                                                 |
| `libraryBindings`        | `array`           | Always an empty array                                                                                                                                                                             |
| `memoryOrgId`            | `string \| null`  | Always null                                                                                                                                                                                       |
| `memoryJobId`            | `string \| null`  | Always null                                                                                                                                                                                       |
| `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                                                                                                                               |
| `digest`                 | `string`          | The value to send as baseDigest to the APIs that change a placement (steps and sweep). It is made from the steps, runtime settings, and sweeps, and does not change when the Agent itself changes |

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

Gets all placements of a project.

#### 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                                                          |

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID                                                 |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |
| `404`  | `project_not_found` | The project does not exist, or you are not a member                     |

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

Gets one placement.

#### Response Fields (200 OK)

| Field       | Type     | Description                                          |
| ----------- | -------- | ---------------------------------------------------- |
| `placement` | `object` | The placement. See "Placement Fields" for the fields |

#### Error Responses

| Status | code                  | Description                                                                                         |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`   | projectId or placementId is not a UUID                                                              |
| `403`  | `forbidden`           | Called with a system integration token                                                              |
| `403`  | `sso_required`        | The user record is not linked to an account of the authorization server                             |
| `404`  | `placement_not_found` | The placement does not exist, it belongs to another project, or you are not a member of the project |

### GET`/v1/projects/agent-candidates`

Gets the registered Agents that can be placed in steps. Pass the returned `marketplaceAgentId` to the API that places a placement (`POST /v1/projects/{projectId}/placements`). All active registered Agents are returned in the order of their display names.

- When `project_type` is `"workflow"`, the registered Agents that have a workflow definition are returned. Only registered Agents whose `certified` is true can be placed in a workflow project.
- When `project_type` is `"cycle"`, all active registered Agents are returned (`certified` and `certificationProblem` are null).

#### Query Parameters

| Parameter      | Type     | Default      | Description                                                |
| -------------- | -------- | ------------ | ---------------------------------------------------------- |
| `project_type` | `string` | `"workflow"` | The type of the project to place in: "workflow" or "cycle" |

#### Response Fields (200 OK)

| Field                               | Type              | Description                                                                                   |
| ----------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
| `candidates`                        | `array`           | Array of registered Agents that can be placed                                                 |
| `candidates[].marketplaceAgentId`   | `string \| null`  | ID of the registered Agent. Pass it to the API that places a placement                        |
| `candidates[].displayName`          | `string \| null`  | Display name                                                                                  |
| `candidates[].description`          | `string \| null`  | Description                                                                                   |
| `candidates[].iconUrl`              | `string \| null`  | URL of the icon                                                                               |
| `candidates[].tags`                 | `array`           | Array of tags                                                                                 |
| `candidates[].certified`            | `boolean \| null` | Whether the Agent is certified for use in workflows ("workflow" only)                         |
| `candidates[].certificationProblem` | `string \| null`  | Code of the reason why the Agent is not certified. null when it is certified, and for "cycle" |

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | project\_type is neither "workflow" nor "cycle"                         |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |

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

Places a registered Agent in steps of a project. Only owners can call this API. Specify the registered Agent with the `marketplaceAgentId` of the Agent candidates (`GET /v1/projects/agent-candidates`).

#### Request Body

| Field                | Type     | Required | Description                                                                                                                                        |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `marketplaceAgentId` | `string` | Yes      | ID of the registered Agent to place (the marketplaceAgentId of the Agent candidates; 1 to 100 characters; leading and trailing spaces are removed) |
| `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.
- `agentId` cannot be sent (sending it returns `400 Bad Request` (`invalid_parameter`)).
  <!-- -->
- 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.

#### Response (201 Created)

| Field       | Type     | Description                                                 |
| ----------- | -------- | ----------------------------------------------------------- |
| `placement` | `object` | The placed placement. See "Placement Fields" for the fields |

#### Error Responses

| Status | code                        | Description                                                                                                                                                                                                     |
| ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`         | projectId is not a UUID, marketplaceAgentId is missing, empty, or longer than 100 characters, agentId was sent, 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 registered Agent in marketplaceAgentId does not exist or is not active                                                                                                                                      |
| `400`  | `agent_not_certified`       | A registered Agent that is not certified for use in workflows was specified for a workflow project                                                                                                              |
| `400`  | `lanes_not_for_marketplace` | A registered Agent was placed in a project that has lanes                                                                                                                                                       |
| `403`  | `forbidden`                 | Called with a system integration token                                                                                                                                                                          |
| `403`  | `owner_only`                | A member who is not an owner                                                                                                                                                                                    |
| `403`  | `sso_required`              | The user record is not linked to an account of the authorization server                                                                                                                                         |
| `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)                                                                                                                                                         |
| `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}/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). Past executions of a removed placement remain in the execution history with the original placement ID (`placementId`).

#### Response (200 OK)

| Field         | Type      | Description                                    |
| ------------- | --------- | ---------------------------------------------- |
| `placementId` | `string`  | ID of the removed placement                    |
| `deleted`     | `boolean` | Always true                                    |
| `historyKept` | `boolean` | Whether the placement was kept for the records |

#### Error Responses

| Status | code                  | Description                                                                                         |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`   | projectId or placementId is not a UUID                                                              |
| `403`  | `forbidden`           | Called with a system integration token                                                              |
| `403`  | `owner_only`          | A member who is not an owner                                                                        |
| `403`  | `sso_required`        | The user record is not linked to an account of the authorization server                             |
| `404`  | `placement_not_found` | The placement does not exist, it belongs to another project, or you are not a member of the project |

### 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) |

#### Response (200 OK)

| Field       | Type     | Description                                        |
| ----------- | -------- | -------------------------------------------------- |
| `placement` | `object` | The placement after the change (with a new digest) |

#### 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                                                                                                                                        |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                 |
| `403`  | `owner_only`             | A member who is not an owner                                                                                                                                                           |
| `403`  | `sso_required`           | The user record is not linked to an account of the authorization server                                                                                                                |
| `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                                                                                                                                             |
| `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}/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 resumes and false stops                                                                        |
| `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.

#### Response (200 OK)

| Field       | Type     | Description                                        |
| ----------- | -------- | -------------------------------------------------- |
| `placement` | `object` | The placement after the change (with a new digest) |

#### 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`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                                      |
| `403`  | `owner_only`             | A member who is not an owner                                                                                                                                                                                                                                                                                                                                                                                                                |
| `403`  | `sso_required`           | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                                                                                                                                                                     |
| `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                                                                                                                                                                                                                                                                                                                                                                                                  |
| `409`  | `principal`              | The principal that runs the project (the user who created it) cannot be confirmed                                                                                                                                                                                                                                                                                                                                                           |
| `409`  | `not_marketplace`        | The placement is not of a registered Agent (only placements of registered Agents can have a schedule)                                                                                                                                                                                                                                                                                                                                       |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                                                                                                                                                                                                                                        |

## Triggers

For a cycle project, firing a webhook trigger runs the placement tied to the trigger once, as an extra run. Trigger IDs can be read from `triggers` of Get Project. Add, change, and delete triggers on the screen.

### Endpoint List

| メソッド | エンドポイント                                              | 説明                                         |
| ---- | ---------------------------------------------------- | ------------------------------------------ |
| POST | `/v1/projects/{projectId}/triggers/{triggerId}/fire` | Fire a trigger to run once as an extra run |

### 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. Each fire is accepted separately and is **never merged** into an earlier fire. Fires to the same step of the same agent placement are processed one at a time, in the order they were accepted.

#### 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 |

#### 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 is fixed per combination of agent placement and step: fires to the same combination return the same value (it does not change per fire). 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`  | `owner_only`             | The caller is a member of the project but not an owner                                                                              |
| `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`  | `placement_unavailable`  | The target agent placement does not exist, or is not in a state that can run                                                        |
| `409`  | `event_conflict`         | The same eventId was sent with a different payload                                                                                  |
| `413`  | `body_too_large`         | The request body exceeds 16 KiB                                                                                                     |
| `429`  | `queue_full`             | The number of fires waiting to run on the same step of the same agent placement has reached the limit (20)                          |

### 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. The `jobId` is the same for each combination of a placement and a step, so it cannot tell executions apart either. Each fire becomes a separate execution, and the executions of the same placement run one at a time. Filter the execution history by the placement of the trigger (`placementId`) and the time of the fire (`from`) to find it.

## 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

| メソッド  | エンドポイント                                                   | 説明                                              |
| ----- | --------------------------------------------------------- | ----------------------------------------------- |
| POST  | `/v1/projects/{projectId}/runs`                           | Start a workflow run                            |
| GET   | `/v1/projects/{projectId}/runs/{runId}`                   | Get a workflow run                              |
| GET   | `/v1/projects/{projectId}/runs`                           | List workflow runs                              |
| GET   | `/v1/projects/{projectId}/runs/{runId}/config`            | Get the settings at the start of a workflow run |
| PATCH | `/v1/projects/{projectId}/runs/{runId}`                   | Set or clear the deadline of a workflow run     |
| PUT   | `/v1/projects/{projectId}/runs/{runId}/approvers`         | Reassign the reviewers of a workflow run        |
| GET   | `/v1/projects/{projectId}/artifacts`                      | List the artifacts of a workflow run            |
| GET   | `/v1/projects/{projectId}/artifacts/{artifactId}/content` | Get the content of an artifact                  |

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

| パラメータ     | 型     | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                                          |
| --------- | ----- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload` | `any` | —  | The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. The agent of the first step receives it in context.start\_input (see "Request of a run started from outside" in the marketplace workflow guide). 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

```bash
curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: nightly-batch-20260917" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"ticketId": "INC-1024", "summary": "A user cannot sign in"}}'
```

#### 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                                                                                              |
| `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`  | `owner_only`                      | The caller is a member of the project but not an owner                                                               |
| `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`  | `mixed_runtime`                   | Registered agents and other agents are placed in the same project                                                    |
| `409`  | `agent_not_certified`             | A registered agent placed in the project is not certified for use in workflows                                       |
| `409`  | `lanes_not_for_marketplace`       | The flow of the project has lanes (a project of registered agents cannot proceed with lanes)                         |
| `400`  | `invalid_parameter`               | A value in the start input is invalid                                                                                |
| `400`  | `missing_input`                   | An input file the step needs is missing (the previous step did not produce it, or it was not specified)              |
| `400`  | `duplicate_target_path`           | Two or more input files would be placed at the same target path                                                      |
| `400`  | `mp_placement_not_in_snapshot`    | The registered agent of the step is not in the configuration taken when the run started                              |
| `400`  | `connection_version_missing`      | The connection version is not saved                                                                                  |
| `400`  | `invalid_runtime_config`          | The runtime settings of the placement do not match the registered agent definition                                   |
| `400`  | `input_binding_cycle`             | The input bindings form a cycle                                                                                      |
| `400`  | `input_binding_forward_reference` | An input refers to the output of a later step that has not run yet                                                   |
| `400`  | `input_binding_unknown_output`    | An output specified as an input does not exist in the source registered agent                                        |
| `400`  | `artifact_format_mismatch`        | The format of an artifact specified as an input differs from the required format                                     |
| `400`  | `artifact_digest_missing`         | An artifact specified as an input has no digest                                                                      |
| `400`  | `invalid_config`                  | The settings do not match the registered agent definition                                                            |
| `409`  | `artifact_not_ready`              | An artifact specified as an input is not ready yet (or differs from the content that was reviewed)                   |
| `409`  | `origin_conflict`                 | A different payload was sent with the same Idempotency-Key (the same origin was already used with different content) |
| `409`  | `connection_version_unavailable`  | The connection version cannot be confirmed (the connection target or permissions changed after approval)             |
| `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 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)     |

#### 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 |
| `originType`                      | `string \| null` | How the run started. One of "manual" (started from the UI), "api" (started through the API) 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. 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 service account name). null if unknown, and null otherwise                                                                                                                                                                              |
| `startedAt`                       | `string \| null` | Start time (ISO 8601). null before it starts                                                                                                                                                                                                                                              |
| `endedAt`                         | `string \| null` | End time (ISO 8601). null before it ends                                                                                                                                                                                                                                                  |
| `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                                                                                                           |
| `runtimeKind`                     | `string \| null` | Kind of runtime. "marketplace" (a run of registered agents) or "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. Used by runs of registered agents; null for other 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                                                                                                                                                                                                                              |
| `steps[].conversationId`          | `string \| null` | ID of the conversation of the agent execution. null for runs of registered agents                                                                                                                                                                                                         |
| `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)                                                                                                                                                                                                                                         |
| `steps[].lane`                    | `string \| null` | Always "main"                                                                                                                                                                                                                                                                             |
| `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                                                                                                                                                                                                                                                                |
| `steps[].outcome`                 | `string \| null` | Result of the agent execution. 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                                                                                                                                                                                                                                                                |
| `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. 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` | Always null                                                                                                                                                                                                                                                                               |
| `steps[].resumeReason`            | `string \| null` | Always null                                                                                                                                                                                                                                                                               |
| `steps[].supersededBy`            | `string \| null` | Always null                                                                                                                                                                                                                                                                               |
| `steps[].gateKind`                | `string \| null` | Always null                                                                                                                                                                                                                                                                               |
| `steps[].connectionConfirmOf`     | `string \| null` | Always null                                                                                                                                                                                                                                                                               |
| `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`          | Always an empty array                                                                                                                                                                                                                                                                     |

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 or the API) | User ID                                                    | null                                          |
| A service account               | "client:" followed by the client ID of the service account | Name of the service account (null if unknown) |
| A schedule                      | null                                                       | null                                          |

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

#### Response Example

<!-- -->

<!-- -->

```json
{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "client:order-batch",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "marketplace",
  "cancelRequestedAt": null,
  "deadlineAt": null,
  "configRevision": 1,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": null,
      "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
    }
  ],
  "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                                         |
| `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) |

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

#### 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`  | `forbidden`         | Called with a system integration token                                                                                                      |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                                                                     |
| `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, <!-- -->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).

#### 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)                                                                                                                                                                                                                                                                                                                                                                |
| `lanes`         | `array \| null`  | All steps are in one "main" lane (name is null)                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `forks`         | `array \| null`  | Always an empty array                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `joins`         | `array \| null`  | Always an empty array                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `placements`    | `array \| null`  | The placements at that time (placementId, agentId, name, goal, guardrail, skills, playbookId, playbookName, runtimeConfigs, libraryBindings, sweeps, and stepIds). runtimeConfigs and libraryBindings have the same form as the placement fields. goal, guardrail, skills, and playbookId are the values at the start. libraryBindings is always an empty array. goal, guardrail, playbookId, and playbookName are always null, and skills is always an empty array |
| `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 on the admin screen, 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.

#### Error Responses

| Status | code                | Description                                                                                                                 |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId or runId is not a UUID                                                                                            |
| `403`  | `forbidden`         | Called with a system integration token                                                                                      |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                                                     |
| `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). Only owners 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.

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

#### 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`  | `forbidden`                 | Called with a system integration token                                                                                      |
| `403`  | `owner_only`                | A member who is not an owner                                                                                                |
| `403`  | `sso_required`              | The user record is not linked to an account of the authorization server                                                     |
| `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<!-- -->. Only owners 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.

#### 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         |

#### 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`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                             |
| `403`  | `owner_only`             | A member who is not an owner                                                                                                                                                                                                       |
| `403`  | `sso_required`           | The user record is not linked to an account of the authorization server                                                                                                                                                            |
| `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                                                                                                                                                                               |

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

Gets all artifacts made by the steps of a workflow run, in the order they were made. Read the content with the API that gets the content of an artifact (`GET /v1/projects/{projectId}/artifacts/{artifactId}/content`). Only members of the project can read them.

#### Path Parameters

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

#### Query Parameters

| Parameter | Type     | Default | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `run_id`  | `string` | `—`     | Required. ID of the workflow run (UUID) |

#### Response Fields (200 OK)

| Field                    | Type             | Description                                               |
| ------------------------ | ---------------- | --------------------------------------------------------- |
| `artifacts`              | `array`          | Array of artifacts                                        |
| `artifacts[].artifactId` | `string \| null` | Artifact ID (UUID)                                        |
| `artifacts[].runId`      | `string \| null` | ID of the workflow run                                    |
| `artifacts[].name`       | `string \| null` | Name of the artifact                                      |
| `artifacts[].mimeType`   | `string \| null` | MIME type of the artifact                                 |
| `artifacts[].size`       | `number \| null` | Size (bytes)                                              |
| `artifacts[].status`     | `string \| null` | "ready" (readable) or "uploading" (not fully written yet) |
| `artifacts[].createdAt`  | `string \| null` | When the artifact was made (ISO 8601)                     |

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID, or run\_id is missing or not a UUID            |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |
| `404`  | `project_not_found` | The project does not exist, or you are not a member                     |
| `404`  | `run_not_found`     | The workflow run does not exist, or belongs to another project          |

### GET`/v1/projects/{projectId}/artifacts/{artifactId}/content`

Gets the content of an artifact. You can also call it with `HEAD`. The same headers are returned without the body, so you can check the size first. Reading it with `GET` leaves a view (`forensic.viewed`) in the records (audit trail) (`HEAD` does not).

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                                                          |
| ------------ | -------- | -- | ----------------------------------------------------------- |
| `projectId`  | `string` | 必須 | Project ID (UUID)                                           |
| `artifactId` | `string` | 必須 | Artifact ID (UUID). The artifactId in the list of artifacts |

#### Response (200 OK)

The content of the artifact is returned as it is.

| Response header          | Description                           |
| ------------------------ | ------------------------------------- |
| `Content-Type`           | MIME type of the artifact             |
| `Content-Length`         | Size (bytes)                          |
| `X-Content-Type-Options` | "nosniff"                             |
| `Content-Disposition`    | "attachment" (returned as a download) |

#### Error Responses

| Status | code                 | Description                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | projectId or artifactId is not a UUID                                                            |
| `403`  | `forbidden`          | Called with a system integration token                                                           |
| `403`  | `sso_required`       | The user record is not linked to an account of the authorization server                          |
| `404`  | `project_not_found`  | The project does not exist, or you are not a member                                              |
| `404`  | `artifact_not_found` | The artifact does not exist, belongs to another project, or is not an artifact of a workflow run |
| `409`  | `artifact_not_ready` | The artifact is not fully written yet                                                            |

## Executions

An execution is one run of an Agent. 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

| メソッド | エンドポイント                                                        | 説明                               |
| ---- | -------------------------------------------------------------- | -------------------------------- |
| GET  | `/v1/projects/{projectId}/executions`                          | Get the execution history        |
| GET  | `/v1/projects/{projectId}/executions/{executionId}`            | Get the result of an execution   |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/operations` | Get the list of tool calls       |
| GET  | `/v1/projects/{projectId}/executions/{executionId}/timeline`   | Get the timeline of an execution |

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

<!-- -->

### 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), "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. 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)                                                                                                                                                                                                       |

#### 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 cycle, a relaunch is a new execution, and it does not increase)                                                                         |
| `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)                                                                                               |
| `executions[].errorMessage`    | `string \| null`  | Error message (cycle)                                                                                                                                                                                       |
| `executions[].originType`      | `string \| null`  | How it started. For a workflow, how the workflow run started ("manual", "api", or "cron"); for a cycle, "cron" (sweep) or "webhook" (trigger fire)                                                          |
| `executions[].actorLabel`      | `string \| null`  | Display name of a starter that is not a user (the name of the service account)                                                                                                                              |
| `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`  | Always null                                                                                                                                                                                                 |
| `hasMore`                      | `boolean`         | Whether there is a next page                                                                                                                                                                                |
| `cursor`                       | `string`          | Cursor for the next page. Included only when hasMore is true                                                                                                                                                |

#### 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`  | `forbidden`         | Called with a system integration token                                                                                                                                                                                                                                                                                                                       |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                                                                                      |
| `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) |

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

| Field                                 | Type             | Description                                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectionConfirmOf`                 | `string \| null` | Always null                                                                                                                                                                                                                                                                                               |
| `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)                                                                                                                                               |
| `library`                             | `object`         | Project library records. inputs and writes are always empty arrays                                                                                                                                                                                                                                        |

- 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.
- <!-- -->
  The `inputs` and `writes` of `library` are always empty arrays.
  <!-- -->
- Read each tool call in the list of tool calls.

#### Error Responses

| Status | code                  | Description                                                                                      |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`   | projectId is not a UUID, or executionId is neither rs:\<number> nor a UUID                       |
| `403`  | `forbidden`           | Called with a system integration token                                                           |
| `403`  | `sso_required`        | The user record is not linked to an account of the authorization server                          |
| `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`.

#### Response Fields (200 OK)

| Field                         | Type             | Description                                                                                                               |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `operations`                  | `array`          | Array of calls                                                                                                            |
| `operations[].operationId`    | `string \| null` | Call ID                                                                                                                   |
| `operations[].kind`           | `string \| null` | Kind of row. "access" is 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                                                                                                        |
| `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.

#### 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`  | `forbidden`           | Called with a system integration token                                                           |
| `403`  | `sso_required`        | The user record is not linked to an account of the authorization server                          |
| `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) |

#### Response Fields (200 OK)

| Field                        | Type             | Description                                                                                                       |
| ---------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `rootExecutionId`            | `string`         | Execution ID                                                                                                      |
| `origin`                     | `string \| null` | How the execution started                                                                                         |
| `owner`                      | `object \| null` | Principal of the execution                                                                                        |
| `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`         | Record ID. For "tool.access" rows, it matches operationId (row:\<key>) in the list of tool calls                  |
| `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                                                                               |
| `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`, `ref`, and `available`. The contents of `meta` differ by kind of record, and their field names are returned as recorded (snake\_case). One page is up to 64 KiB.

#### 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`  | `forbidden`           | Called with a system integration token                                                                       |
| `403`  | `sso_required`        | The user record is not linked to an account of the authorization server                                      |
| `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                                                                         |

<!-- -->

## Files

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

### Endpoint List

| メソッド | エンドポイント                                  | 説明                        |
| ---- | ---------------------------------------- | ------------------------- |
| GET  | `/v1/projects/{projectId}/files/content` | Get the content of a file |

### 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). 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 the token used for MCP<!-- -->, 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, or evidence.files\[].filepath in a review request) |
| `version_id` | `string` | `—`     | ID of a version. The current version if omitted                                                                       |

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.

#### 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 (bytes)                                                  |
| `X-Content-Type-Options` | "nosniff"                                                          |
| `Content-Disposition`    | "attachment" for HTML, SVG, and XML files (returned as a download) |

#### 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`  | `forbidden`         | Called with a system integration token                                     |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server    |
| `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/marketplace/api/reference/user-api-reference.md#artifacts) (`GET /v1/files/proxy`).

## 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, <!-- -->and members<!-- --> (including changes made on the screen). <!-- -->Other changes<!-- --> to steps, placements, sweeps, triggers, connectors, and notifications are not kept.

### Endpoint List

| メソッド | エンドポイント                          | 説明                            |
| ---- | -------------------------------- | ----------------------------- |
| GET  | `/v1/projects/{projectId}/audit` | Get the records (audit trail) |

### 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)                             |

#### 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:\<client ID> for a system integration, 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.

#### 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`  | `forbidden`         | Called with a system integration token                                                                                                                                            |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                                                                                                           |
| `404`  | `project_not_found` | The project does not exist, or you are not a member                                                                                                                               |

## KPI

Gets the same values as "KPI" in the overview on the screen. For how they are counted, see the [Results Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/reference/results-ref.md).

### Endpoint List

| メソッド | エンドポイント                        | 説明           |
| ---- | ------------------------------ | ------------ |
| GET  | `/v1/projects/{projectId}/kpi` | Get the KPIs |

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

Gets the KPIs of a project. Only project members can read them (even for a shared project, a non-member gets 404).

#### Query Parameters

| Parameter | Type      | Default | Description                                        |
| --------- | --------- | ------- | -------------------------------------------------- |
| `days`    | `integer` | `30`    | Period (the most recent days). One of 7, 30, or 90 |

#### 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 always 0                                             |
| `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)                                                                 |
| `human`              | `object`         | Review handling (reviewsPerRun, gateWaitMedianMinutes, and interventions)                                                                                     |

The Agent completion rate, `runs`, `gates`, and `human` count executions, workflow runs, and review requests that started in the period.

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID, or days is not 7, 30, or 90                    |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |
| `404`  | `project_not_found` | The project does not exist, or you are not a member                     |

<!-- -->

## 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.<!-- --> The reviewers decide whether to proceed, send it back, or reject it<!-- -->. 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) and the owners of the project can read it. Other users get `404 Not Found` (`workitem_not_found`).
- Only reviewers can decide and extend the due date. An owner who is not a reviewer cannot (`403 Forbidden`, `not_gate_owner`).

### Endpoint List

| メソッド  | エンドポイント                               | 説明                                      |
| ----- | ------------------------------------- | --------------------------------------- |
| GET   | `/v1/workitems`                       | Get the list of review requests         |
| GET   | `/v1/workitems/{workItemId}`          | Get a review request                    |
| POST  | `/v1/workitems/{workItemId}/decision` | Decide a review request                 |
| PATCH | `/v1/workitems/{workItemId}`          | Extend the due date of a review request |

### 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)                                                                                      |

#### 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`  | Always "blocking" (wait for the reviewer's decision)                   |
| `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)                           |
| `hasMore`                     | `boolean`         | Whether there is a next page                                           |
| `cursor`                      | `string`          | Cursor for the next page. Included only when hasMore is true           |

#### 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`  | `forbidden`         | Called with a system integration token                                                                                                                    |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                                                                                   |

### 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) |

#### 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)                                                                                                       |
| `workitem.stepId`             | `string \| null` | ID of the step that asked for the review (a review step, or an Agent step that asked for a review because of its outcome)                                                                                                      |
| `workitem.approverUserIds`    | `array`          | Array of user IDs of the reviewers (the reviewers when the review request was created)                                                                                                                                         |
| `workitem.overdueAction`      | `string \| null` | Always "none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting)                                                                                                           |
| `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, and destinationStepId). completesRun is whether proceeding finished the workflow run                                                      |
| `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[].reasonCode`     | `string \| null` | Reason                                                                                                                                                                                                                         |
| `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                     |
| `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) or "manual" (manual work)                                                                                                                                           |
| `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)                                                                                                                 |
| `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`          | Always an empty array (destinations cannot be set in the Marketplace edition)                                                                                                                         |
| `connector`        | `object \| null` | Always null                                                                                                                                                                                           |
| `service`          | `string \| null` | Always null                                                                                                                                                                                           |
| `mode`             | `string \| null` | Always null                                                                                                                                                                                           |
| `tool`             | `string \| null` | Always null                                                                                                                                                                                           |
| `waitMinutes`      | `number \| null` | Always null                                                                                                                                                                                           |

Information for the decision (`gate`):

| Field                   | Type             | Description                                                                                                                                          |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contextVersion`        | `number`         | Version of the review request (1 or more). Included only for a versioned review (a workflow review). Send it as is in contextVersion of the decision |
| `basisDigest`           | `string \| null` | Digest of the review material (64 hexadecimal characters). Included only when contextVersion is. Send it as is in basisDigest of the decision        |
| `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                                                          |
| `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`          | Always an empty array (destinations cannot be set in the Marketplace edition)                                                                        |
| `lane`                  | `object \| null` | Lane of the step that asked for the review (laneId, name, and position). null when there are no lanes                                                |

#### Error Responses

| Status | code                 | Description                                                             |
| ------ | -------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | workItemId is not a UUID                                                |
| `403`  | `forbidden`          | Called with a system integration token                                  |
| `403`  | `sso_required`       | The user record is not linked to an account of the authorization server |
| `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 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 |
| `commandId`        | `string`  | —        | A value to identify resends (up to 128 characters)                                                                                                        |
| `contextVersion`   | `integer` | —        | gate.contextVersion of the review request you read before deciding (an integer of 1 or more). Required when gate includes it                              |
| `basisDigest`      | `string`  | —        | gate.basisDigest of the review request you read before deciding (64 lowercase hexadecimal characters). Required when gate includes it                     |

- 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 versioned review, 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` and `gate.basisDigest`.

#### 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 |

#### 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, contextVersion is not an integer of 1 or more, basisDigest is not 64 lowercase hexadecimal characters, or a field has the wrong type or length |
| `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`  | `invalid_destination`      | destinationId was sent (review requests in the Marketplace edition have no destinations)                                                                                                                                                                                                        |
| `400`  | `basis_required`           | contextVersion and basisDigest were not sent for a versioned review                                                                                                                                                                                                                             |
| `403`  | `forbidden`                | Called with a system integration token                                                                                                                                                                                                                                                          |
| `403`  | `sso_required`             | The user record is not linked to an account of the authorization server                                                                                                                                                                                                                         |
| `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. Only reviewers can call this API. Extending it also clears the overdue flag (`overdue`).

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

#### Response Fields (200 OK)

| Field      | Type     | Description                                                                                         |
| ---------- | -------- | --------------------------------------------------------------------------------------------------- |
| `workitem` | `object` | The review request after the extension. The fields are the same as workitem in Get a Review Request |

If reading the review request back after extending the due date fails, `502 Bad Gateway` (`upstream_connection_error`) is returned. The due date may already have been extended, so check `expiresAt` with Get a Review Request before resending.

#### 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`  | `forbidden`                 | Called with a system integration token                                                                                 |
| `403`  | `sso_required`              | The user record is not linked to an account of the authorization server                                                |
| `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`  | `invalid_state`             | It is not waiting for review (for example, it was cancelled)                                                           |
| `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` | Reading the review request back after extending the due date failed (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 the queue on the screen.

- The project queue (`GET /v1/projects/{projectId}/queue`) returns all rows of the project. Members of the project can read it.
- Your queue (`GET /v1/queue`) returns the rows you are assigned to, across the projects you take part in.
- To act on a row, pass the row's ID 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`      |

### Endpoint List

| メソッド | エンドポイント                          | 説明                                        |
| ---- | -------------------------------- | ----------------------------------------- |
| GET  | `/v1/projects/{projectId}/queue` | Get the queue of a project                |
| GET  | `/v1/queue`                      | Get the queue of rows you are assigned to |

### 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                                          |

### 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 row ID, 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) |

#### Response Fields (200 OK)

| Field                               | Type              | Description                                                                                                                                                                                                                                                                                                       |
| ----------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queueItems`                        | `array`           | Array of queue rows                                                                                                                                                                                                                                                                                               |
| `queueItems[].queueItemId`          | `string`          | Row ID (in the form \<kind>:\<ID>)                                                                                                                                                                                                                                                                                |
| `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 |
| `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                                                                                                                                                                                                                                                      |

#### 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`  | `forbidden`         | Called with a system integration token                                                      |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server                     |
| `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, in order of priority. The query parameters, response fields, and order are the same as the project queue.

#### Error Responses

| Status | code                | Description                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------- |
| `400`  | `invalid_parameter` | kind is not one of the values above, or limit or cursor is invalid      |
| `403`  | `forbidden`         | Called with a system integration token                                  |
| `403`  | `sso_required`      | The user record is not linked to an account of the authorization server |

## 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). A connector that was disabled or deleted on the administration screen returns `404 Not Found` (`connector_not_found`).
- Sign-in to a connector is done on the project screen.

### Endpoint List

| メソッド | エンドポイント                             | 説明                   |
| ---- | ----------------------------------- | -------------------- |
| GET  | `/v1/connectors/mcp/{connectionId}` | Get an MCP connector |
| GET  | `/v1/connectors/a2a/{connectionId}` | Get an A2A connector |

### 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 on the administration screen.

#### Path Parameters

| パラメータ          | 型        | 必須 | 説明                                                   |
| -------------- | -------- | -- | ---------------------------------------------------- |
| `connectionId` | `string` | 必須 | Connector ID (a positive integer of up to 16 digits) |

#### 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                           |

#### Error Responses

| Status | code                  | Description                                               |
| ------ | --------------------- | --------------------------------------------------------- |
| `400`  | `invalid_parameter`   | connectionId is not a positive integer of up to 16 digits |
| `403`  | `forbidden`           | Called with a system integration token                    |
| `404`  | `connector_not_found` | The connector does not exist or is disabled               |

### GET`/v1/connectors/a2a/{connectionId}`

Gets an A2A connector and its agent card. The agent card is the one saved on the administration screen.

#### Path Parameters

| パラメータ          | 型        | 必須 | 説明                                                   |
| -------------- | -------- | -- | ---------------------------------------------------- |
| `connectionId` | `string` | 必須 | Connector ID (a positive integer of up to 16 digits) |

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

#### Error Responses

| Status | code                  | Description                                               |
| ------ | --------------------- | --------------------------------------------------------- |
| `400`  | `invalid_parameter`   | connectionId is not a positive integer of up to 16 digits |
| `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<!-- -->. For details, see [Conversation Management in the User API Reference (Conversations, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md#conversations).

- You can find `conversationId` in `conversationId` of the execution history and the execution result.
- Only the person who created the project (for a copied project, the person who copied it) can read it, because project executions run in the creator's name (see [Who decides what](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/roles.md)). Other owners and members get `404 Not Found`. It cannot be read from a system integration.
- An execution of a workflow step run by a registered Agent has no conversation (conversationId is null). 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                                                                                                                                                                                                                                           |
| `403 Forbidden`              | No access permission to the resource                                                                                                                                                                                                                                  |
| `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                                                                                                                                                                                                    |
| `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.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"
  }
}
```
