# System Integration API Reference

Endpoint specification and error codes for the System Integration API of the Marketplace edition.

> **note**
>
> This page is the reference for the APIs called with a system integration (service account) token. A system integration can use Chat, Conversation Management, File Management, Artifact Retrieval, Search, Registered Agents and nine project APIs ([Projects](#projects)). For the APIs called with an application (sign-in from an external tool) token, see the [User API Reference (Conversations, Organizations)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md) and the [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md). The Library, Library Agent, Skills, Playbooks, Persona, User Management, Logs and Shared Memory APIs are available in the SaaS edition only. See the [User API Reference (SaaS)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md) and the [System Integration API Reference (SaaS)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md) for those.

## Base URL

Send all API requests to the following base URL. Replace `<your-domain>` with the domain of your deployment.

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 service account token. The APIs that can be called with an application (sign-in from an external tool) token are in the User API References. 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).

> **Chat API**
>
> In the Marketplace edition the Chat API requires the `agentId` parameter and always runs with `stream: true`. See the [Call the API](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/quickstart/call-api.md) for details.

## Common Rules

These rules apply to the APIs on this page.

### How requests are handled

The APIs on this page handle requests as follows. See each endpoint's description and error responses for endpoint-specific handling.

| What you sent                                                                                                                                             | How it is handled                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Query parameters and body fields not in the specification                                                                                                 | Ignored. However, even items not listed on this page may return `400 Bad Request` if their type or value is wrong, when the service accepts them |
| An invalid value for a query parameter in the specification                                                                                               | `400 Bad Request`                                                                                                                                |
| An invalid URL encoding in a path parameter value (a `%` sequence)                                                                                        | `400 Bad Request` (`invalid_parameter`)                                                                                                          |
| A malformed JSON body                                                                                                                                     | `400 Bad Request` (`invalid_body`)                                                                                                               |
| A body other than `Content-Type: application/json`, or a body with an unsupported character set (`charset`), sent to an endpoint that accepts a JSON body | `415 Unsupported Media Type` (`unsupported_media_type`)                                                                                          |
| A body other than `multipart/form-data` sent to a file upload                                                                                             | `415 Unsupported Media Type`                                                                                                                     |
| A body field of the wrong type                                                                                                                            | `400 Bad Request`                                                                                                                                |

If reading the body results in `400` (malformed JSON and so on) or `413` (the size limit was exceeded and so on), that is returned before `415`.

<!-- -->

### Pagination

List endpoints support cursor-based pagination.

| Parameter | Type      | Description                                                                                                       |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | Number of items per page (1-100). Defaults to 50.                                                                 |
| `cursor`  | `string`  | Cursor value for the next page. Pass the cursor from the previous response as is.                                 |
| `order`   | `string`  | Sort order: "asc" or "desc" (default). Any other value returns 400 Bad Request. Supported on some endpoints only. |

Responses include a `hasMore` field. While it is `true`, pass the `cursor` value in the next request to retrieve the following page.

Cursor-based pagination is available on the list endpoints of [Conversations](#conversations), [Messages](#conversations), [Files](#file-management), [Message search](#search-messages) and [Projects](#projects). Treat `cursor` as opaque: do not interpret it, just pass the previous value back.

## Chat

OpenAI-compatible Chat Completions API. Conversations with the agent are delivered via SSE (Server-Sent Events) streaming.

The Chat API consists of three endpoints. You can send messages, reconnect to existing conversations, and cancel conversations in progress.

SSE Streaming Guide

Detailed explanation of connection flow, response objects, Delta extensions, execution patterns, reconnection, and error handling

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md)

### Endpoint List

| メソッド | エンドポイント                                       | 説明                                                           | Scope (SaaS) |
| ---- | --------------------------------------------- | ------------------------------------------------------------ | ------------ |
| POST | `/v1/chat/completions`                        | Send a chat message and receive a response via SSE streaming | `chat:exec`  |
| GET  | `/v1/chat/completions/:conversationId`        | Reconnect to the SSE stream of a conversation in progress    | `chat:exec`  |
| POST | `/v1/chat/completions/:conversationId/cancel` | Cancel a conversation in progress                            | `chat:exec`  |

Note: The Marketplace edition does not require scopes (authentication only).

### POST`/v1/chat/completions`

Send a message to the agent and receive a response via SSE streaming. Responses are delivered in OpenAI-compatible Chat Completion Chunk format.

#### Request Headers

| ヘッダー            | 必須 | 説明                      |
| --------------- | -- | ----------------------- |
| `Authorization` | 必須 | Bearer \<access\_token> |
| `Content-Type`  | 必須 | application/json        |

#### Request Body

| パラメータ            | 型         | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | --------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`          | `string`  | 必須 | The model ID to use. Specify "AGENTIC STAR".                                                                                                                                                                                                                                                                                                                                        |
| `messages`       | `array`   | 必須 | Array of message objects. At least one user-role message is required. Even if multiple user messages are included, only the last one is processed. Conversation history is managed on the server side, so you do not need to send past exchanges in the messages array. To continue an existing conversation, specify the previous conversation ID in the conversationId parameter. |
| `stream`         | `boolean` | 必須 | Specify true. Currently, only streaming mode is supported.                                                                                                                                                                                                                                                                                                                          |
| `conversationId` | `string`  | —  | Specify a conversation ID to continue an existing conversation. If omitted, a new conversation is created.                                                                                                                                                                                                                                                                          |

#### Edition-Specific Parameters

Marketplace

|                |          |                                                                                                                                                                                                  |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agentId`      | `string` | The ID of the agent to use (required). Use a marketplaceAgentId returned by GET /v1/marketplace-agents.                                                                                          |
| `outputFormat` | `string` | Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept, and links become "text (URL)"). "markdown" preserves Markdown as-is. |

#### Message Object

| パラメータ     | 型                 | 必須 | 説明                                                                                                                                                        |
| --------- | ----------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role`    | `string`          | 必須 | Use "user". "assistant" / "system" are accepted but only "user" is effectively used as the starting point of the agent turn in the current implementation |
| `content` | `string \| array` | 必須 | The message content. A string, or an array of content parts (text / input\_file). The text to be processed must be 1 MB or less in UTF-8.                 |

#### Content Parts (Array Format)

When specifying content as an array, the following part types are available. You can combine text and files in a single message.

| type           | Parameter         | Description                                                        |
| -------------- | ----------------- | ------------------------------------------------------------------ |
| `"text"`       | `text (string)`   | Text message                                                       |
| `"input_file"` | `fileId (string)` | The `fileId` of an uploaded file. Up to 20 files total per request |

#### Request Example

**Create chat completion**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "model": "AGENTIC STAR",
  "agentId": "<your-agent-id>",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Please analyze the sales data"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/chat/completions",
  headers={
      "Authorization": f"Bearer {token}",
      "Content-Type": "application/json",
  },
  json={
      "model": "AGENTIC STAR",
      "agentId": "<your-agent-id>",
      "stream": True,
      "messages": [{"role": "user", "content": "Please analyze the sales data"}],
  },
  stream=True,
)

for line in response.iter_lines():
  if line:
      print(line.decode("utf-8"))
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "AGENTIC STAR",
    agentId: "<your-agent-id>",
    stream: true,
    messages: [{ role: "user", content: "Please analyze the sales data" }],
  }),
}
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
```

**Go**

```go
package main

import (
  "bufio"
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "strings"
)

func main() {
  token := "<access_token>" // Access token obtained in Step 1

  body, _ := json.Marshal(map[string]interface{}{
      "model":  "AGENTIC STAR",
      "agentId": "<your-agent-id>",
      "stream": true,
      "messages": []map[string]string{
          {"role": "user", "content": "Please analyze the sales data"},
      },
  })

  req, _ := http.NewRequest("POST",
      "https://<your-domain>/api/v1/chat/completions",
      bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer "+token)
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  scanner := bufio.NewScanner(resp.Body)
  for scanner.Scan() {
      line := scanner.Text()
      if strings.HasPrefix(line, "data: ") {
          data := line[6:]
          if data == "[DONE]" { break }
          var chunk map[string]interface{}
          json.Unmarshal([]byte(data), &chunk)
          choices, _ := chunk["choices"].([]interface{})
          if len(choices) > 0 {
              delta, _ := choices[0].(map[string]interface{})["delta"].(map[string]interface{})
              if content, ok := delta["content"].(string); ok {
                  fmt.Print(content)
              }
          }
      }
  }
}
```

#### Response Headers

| Header              | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `Content-Type`      | text/event-stream                                                          |
| `X-Conversation-Id` | Conversation ID. For new conversations, a server-generated ID is returned. |
| `X-Message-Id`      | The assistant response message ID.                                         |

#### SSE Response Format

Responses are delivered as SSE events in the following order. Each event is a JSON line prefixed with data:.

SSE Event Flow

1

<!-- -->

. `data: {"choices":[{"delta":{"role":"assistant"}}]}`

2

<!-- -->

. `data: {"choices":[{"delta":{"content":"..."}}]} × N`

3

<!-- -->

. `data: {"choices":[{"finishReason":"stop"}]}`

4

<!-- -->

. `data: [DONE]`

Responses are delivered via SSE (Server-Sent Events) streaming. Each chunk is in OpenAI-compatible ChatCompletionChunk format. For details on the connection lifecycle, response objects, agent extension fields, and error handling, see the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md).

#### Response Example

```text
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"Analyzing"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":" the sales data."},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:01Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{},"finishReason":"stop"}]}

data: [DONE]
```

#### Error Response

Errors before the SSE stream starts are returned in JSON format. Errors during the stream are delivered as SSE chunks.

| Status | Description                                                                                                                                                                                                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input\_file parts in a single request). A malformed JSON body (`code: "invalid_body"`). Or the specified conversationId is archived (`code: "conversation_archived"`) |
| `400`  | The messages array has no message with the user role (`code: "no_user_message"`)                                                                                                                                                                                                                    |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                    |
| `403`  | The specified conversation is a project conversation (`code: "project_conversation"`. Messages cannot be sent to a project conversation)                                                                                                                                                            |
| `404`  | The `fileId` of the specified input\_file was not found (`code: "file_not_found"`)                                                                                                                                                                                                                  |
| `409`  | The specified conversation is currently being processed (`code: "conversation_processing"`)                                                                                                                                                                                                         |

### GET`/v1/chat/completions/:conversationId`

Reconnect to the SSE stream of a conversation in progress. Use this when the agent is processing a long-running task or to recover after a network disconnection.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                         |
| ---------------- | -------- | -- | ------------------------------------------ |
| `conversationId` | `string` | 必須 | The ID of the conversation to reconnect to |

#### Request Example

**Resume SSE stream**

**curl**

```curl
curl https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
  stream=True,
)

for line in response.iter_lines():
  if line:
      print(line.decode("utf-8"))
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
  fmt.Println(scanner.Text())
}
```

#### Response (200 OK)

Reconnects to the SSE stream. The response format is the same as [POST /v1/chat/completions](#chat). The response headers include `X-Conversation-Id` and `X-Message-Id`. For detailed reconnection procedures, see the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md).

#### Error Response

| Status | code        | Description                                                                                                                  |
| ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `not_found` | The conversation was not found, is not in progress, or is not yours (the same applies when conversationId is an empty value) |

### POST`/v1/chat/completions/:conversationId/cancel`

Cancel a conversation in progress. Use this to abort the agent's execution.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                   |
| ---------------- | -------- | -- | ------------------------------------ |
| `conversationId` | `string` | 必須 | The ID of the conversation to cancel |

#### Request Body (optional)

| パラメータ       | 型        | 必須 | 説明                                                                                   |
| ----------- | -------- | -- | ------------------------------------------------------------------------------------ |
| `messageId` | `string` | —  | The ID of the message to cancel (UUID). If omitted, cancels the entire conversation. |

#### Request Example

**Cancel chat**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Cancelled: {data['cancelled']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Cancelled: " + data.cancelled);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field            | Type      | Description                                 |
| ---------------- | --------- | ------------------------------------------- |
| `conversationId` | `string`  | The ID of the cancelled conversation (UUID) |
| `cancelled`      | `boolean` | Always true on successful cancellation      |

#### Response Example

```json
{ "conversationId": "550e8400-...", "cancelled": true }
```

#### Error Response

| Status | Description                                                                                                                                                                                                                                                                                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid conversationId, messageId is not a string, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), or the conversation is archived (`code: "conversation_archived"`)                                                                                                                                                                                        |
| `400`  | The message of messageId does not belong to the specified conversation (`code: "conversation_mismatch"`)                                                                                                                                                                                                                                                                              |
| `400`  | The endpoint of this conversation does not support cancellation (`code: "unsupported_endpoint"`), or cancellation is not enabled in this environment (`code: "post_processing_not_enabled"`)                                                                                                                                                                                          |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                                      |
| `404`  | Conversation not found, or the message cannot be canceled (`code: "message_not_found"`). `message_not_found` is returned in two cases: the message was just sent and could not be canceled after waiting about 10 seconds (sending again in a few seconds cancels it), or the message of messageId does not exist or is not yours (sending again does not cancel it; check messageId) |
| `404`  | The message of messageId is not being processed (it has already finished) (`code: "not_processing"`)                                                                                                                                                                                                                                                                                  |

## Registered Agents

Gets the list of registered agents you can run in chat.

### Endpoints

| メソッド | エンドポイント                  | 説明                     |
| ---- | ------------------------ | ---------------------- |
| GET  | `/v1/marketplace-agents` | List registered agents |

### GET`/v1/marketplace-agents`

Lists every registered agent you can run in chat (`agentId` of `POST /v1/chat/completions`), the active ones only. The same agents also run in MCP (`agentId` of `execute_chat`) where the MCP endpoint is enabled and you use the chat toolset (`?toolsets=chat`, the default), and in A2A (`/v1/a2a/agents/{agentId}/`) where the A2A endpoint is enabled. It is the same list as the MCP `list_agents` tool and can be up to 5 minutes old. In chat, pass `marketplaceAgentId` as `agentId`.

#### Request Example

**List registered agents**

**curl**

```curl
curl "https://<your-domain>/api/v1/marketplace-agents" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/marketplace-agents",
  headers={"Authorization": f"Bearer {token}"},
)

for agent in response.json()["marketplaceAgents"]:
  print(agent["marketplaceAgentId"], agent["displayName"])
```

**TypeScript**

```typescript
const response = await fetch("https://<your-domain>/api/v1/marketplace-agents", {
headers: { "Authorization": "Bearer " + accessToken },
});

const data = await response.json();
data.marketplaceAgents.forEach((agent) => {
console.log(agent.marketplaceAgentId + ": " + agent.displayName);
});
```

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/marketplace-agents", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field                                    | Type       | Description                                                      |
| ---------------------------------------- | ---------- | ---------------------------------------------------------------- |
| `marketplaceAgents`                      | `array`    | Registered agents (all the active ones)                          |
| `marketplaceAgents[].marketplaceAgentId` | `string`   | ID of the registered agent. In chat, pass it as agentId          |
| `marketplaceAgents[].displayName`        | `string`   | Display name                                                     |
| `marketplaceAgents[].description`        | `string`   | Description. The display name for an agent without a description |
| `marketplaceAgents[].tags`               | `string[]` | Tags                                                             |
| `hasMore`                                | `boolean`  | Always false (all of them are returned)                          |

#### Response Example

```json
{
  "marketplaceAgents": [
    {
      "marketplaceAgentId": "sales-report",
      "displayName": "Sales report",
      "description": "Summarizes sales data into a report",
      "tags": ["report"]
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                        | Description                                                     |
| ------ | --------------------------- | --------------------------------------------------------------- |
| `401`  | `—`                         | The token is missing or invalid (see the common errors section) |
| `502`  | `upstream_connection_error` | The list of registered agents could not be read                 |
| `502`  | `upstream_api_error`        | The source of the list returned an error                        |
| `504`  | `upstream_timeout`          | Reading the list did not finish in time                         |

## Conversation Management

List, retrieve message history, delete, and update titles of conversations.

### Endpoint List

| メソッド   | エンドポイント                                      | 説明                            | Scope (SaaS)   |
| ------ | -------------------------------------------- | ----------------------------- | -------------- |
| GET    | `/v1/conversations`                          | List conversations            | `chat:history` |
| GET    | `/v1/conversations/:conversationId/messages` | Get message history           | `chat:history` |
| PATCH  | `/v1/conversations/:conversationId`          | Update conversation title     | `chat:history` |
| DELETE | `/v1/conversations/:conversationId`          | Delete a conversation         | `chat:history` |
| POST   | `/v1/conversations/:conversationId/restore`  | Restore archived conversation | `chat:history` |
| POST   | `/v1/conversations/:conversationId/read`     | Mark a conversation as read   | `chat:history` |

Note: The Marketplace edition does not require scopes (authentication only).

**Archived conversations are deleted automatically once the retention period set by an administrator has passed since they were archived.** Their messages, and the attached and artifact files used only by that conversation, are deleted with them. If no retention period is set, they are not deleted.

#### Operations on archived conversations

Conversations retrieved with `mode=archive` only support read operations (list / message history) and restoration. The following operations return a 400 error (`code: "conversation_archived"`).

| Operation                                                         | Behavior on archived conversations                                 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| `GET /v1/conversations?mode=archive`                              | ✅ Allowed                                                          |
| `GET /v1/conversations/:id/messages`                              | ✅ Allowed (`messages[].archived: true` is added)                   |
| `PATCH /v1/conversations/:id`                                     | ❌ 400 `Archived conversations cannot be modified`                  |
| `DELETE /v1/conversations/:id`                                    | ❌ 400 `Archived conversations cannot be deleted via this endpoint` |
| `POST /v1/chat/completions` (continuing an existing conversation) | ❌ 400 `Cannot send messages to an archived conversation`           |
| `POST /v1/chat/completions/:id/cancel`                            | ❌ 400 `Cannot cancel an archived conversation`                     |
| `POST /v1/conversations/:id/restore`                              | ✅ Restore to active                                                |

### GET`/v1/conversations`

List conversations. Supports cursor-based pagination.

#### Query Parameters

| パラメータ    | 型         | 必須 | デフォルト      | 説明                                                                                                                                                                    |
| -------- | --------- | -- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`  | `integer` | —  | `50`       | Number of items to return (1-100)                                                                                                                                     |
| `cursor` | `string`  | —  | —          | Cursor for the next page (the cursor value from the previous response)                                                                                                |
| `order`  | `string`  | —  | `"desc"`   | "asc" or "desc"                                                                                                                                                       |
| `title`  | `string`  | —  | —          | Filter by title                                                                                                                                                       |
| `mode`   | `string`  | —  | `"active"` | "active" (regular conversations) or "archive" (archived conversations). Switching \`mode\` switches to a different data store, so a \`cursor\` cannot be carried over |

#### Request Example

**List conversations**

**curl**

```curl
curl "https://<your-domain>/api/v1/conversations?limit=10&order=desc" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/conversations",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "order": "desc"},
)

data = response.json()
for conv in data["conversations"]:
  print(conv["title"], conv["conversationId"])
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/conversations?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.conversations.forEach((conv) => {
console.log(conv.title, conv.conversationId);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/conversations?limit=10&order=desc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field                            | Type       | Description                                                                                                                                                                                                                             |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversations`                  | `array`    | Array of conversation objects                                                                                                                                                                                                           |
| `conversations[].conversationId` | `string`   | Unique identifier of the conversation (UUID)                                                                                                                                                                                            |
| `conversations[].title`          | `string`   | Conversation title                                                                                                                                                                                                                      |
| `conversations[].type`           | `string?`  | Kind of conversation: "chat" (chat) or "mail" (started from mail). Conversations of project steps are not in the list (their messages can be read by specifying the conversation ID). Not returned with `mode=archive`                  |
| `conversations[].createdAt`      | `string`   | Creation date and time (ISO 8601)                                                                                                                                                                                                       |
| `conversations[].updatedAt`      | `string`   | Last updated date and time (ISO 8601)                                                                                                                                                                                                   |
| `conversations[].archived`       | `boolean?` | Whether archived. Always `true` when retrieved via `mode=archive`. When `mode=active` returns this field as `true`, it is only because the conversation remained in archive state but was returned by the active list — usually omitted |
| `hasMore`                        | `boolean`  | Whether the next page exists                                                                                                                                                                                                            |
| `cursor`                         | `string`   | Cursor for fetching the next page. Included only when hasMore is true                                                                                                                                                                   |

#### Response Example

```json
{
  "conversations": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Sales data analysis",
      "type": "chat",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}
```

#### Error Response

| Status | code                        | Description                                                                                                                                                                                                                          |
| ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`         | limit is invalid (outside 1-100), mode is not "active" / "archive", order is not "asc" / "desc", cursor is invalid (not a value from the previous response), or title is not a string (for example, it was specified more than once) |
| `502`  | `upstream_connection_error` | The list of conversations could not be retrieved (retry after a while)                                                                                                                                                               |

### GET`/v1/conversations/:conversationId/messages`

Retrieve the message history of a specified conversation. Cursor-based pagination is supported. Retrieving it does not mark the conversation as read (the same goes for reading via MCP or A2A). To mark it as read, call [Mark a conversation as read](#read-conversation).

#### Path Parameters

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

#### Query Parameters

| パラメータ    | 型         | 必須 | デフォルト    | 説明                                                                     |
| -------- | --------- | -- | -------- | ---------------------------------------------------------------------- |
| `limit`  | `integer` | —  | `50`     | Number of items per page (1-100)                                       |
| `cursor` | `string`  | —  | —        | Cursor for the next page (the cursor value from the previous response) |
| `order`  | `string`  | —  | `"desc"` | "asc" or "desc"                                                        |

#### Request Example

**Get messages**

**curl**

```curl
curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
response = requests.get(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages",
  headers={"Authorization": f"Bearer {token}"},
  params={"order": "asc"},
)

messages = response.json()["messages"]
for msg in messages:
  print(f"[{msg['sender']}] {msg['text'][:50]}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const { messages } = await response.json();
messages.forEach((msg) => console.log("[" + msg.sender + "] " + msg.text));
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field                                 | Type       | Description                                                                                                                                                  |
| ------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `messages`                            | `array`    | Array of message objects                                                                                                                                     |
| `messages[].conversationId`           | `string`   | Conversation ID (UUID)                                                                                                                                       |
| `messages[].messageId`                | `string`   | Unique identifier of the message                                                                                                                             |
| `messages[].sender`                   | `string`   | Sender. "User" or "AI"                                                                                                                                       |
| `messages[].text`                     | `string`   | The message body text. If the body is empty, the result (`content`) of the latest task is returned                                                           |
| `messages[].createdAt`                | `string`   | Creation date and time (ISO 8601)                                                                                                                            |
| `messages[].updatedAt`                | `string`   | Last updated date and time (ISO 8601)                                                                                                                        |
| `messages[].status`                   | `object`   | Message processing status                                                                                                                                    |
| `messages[].status.processing`        | `boolean`  | Whether the agent is currently processing                                                                                                                    |
| `messages[].status.unfinished`        | `boolean`  | Whether the agent response was interrupted                                                                                                                   |
| `messages[].tasks`                    | `array`    | Array of tasks executed by the agent (see below)                                                                                                             |
| `messages[].deliverables`             | `array`    | Array of artifacts generated by the agent. Included only when present                                                                                        |
| `messages[].deliverables[].filename`  | `string`   | Artifact file name                                                                                                                                           |
| `messages[].deliverables[].filepath`  | `string`   | Artifact file path                                                                                                                                           |
| `messages[].deliverables[].source`    | `string`   | `"agent"` (agent-generated) or `"user"` (user-uploaded)                                                                                                      |
| `messages[].deliverables[].isPrimary` | `boolean`  | Whether it is a primary artifact                                                                                                                             |
| `messages[].deliverables[].createdAt` | `string`   | Creation date and time (ISO 8601 format). An empty string when unknown                                                                                       |
| `messages[].deliverables[].mimeType`  | `string`   | MIME type (e.g., `"application/pdf"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined                                          |
| `messages[].deliverables[].size`      | `number?`  | File size (bytes). Omitted when 0 or below                                                                                                                   |
| `messages[].files`                    | `array?`   | Array of user-uploaded files. Included only when present for messages with `sender: "User"`                                                                  |
| `messages[].files[].fileId`           | `string`   | Unique identifier of the file (UUID)                                                                                                                         |
| `messages[].files[].mimeType`         | `string`   | MIME type (e.g., `"image/png"`, `"application/pdf"`)                                                                                                         |
| `messages[].files[].width`            | `number?`  | Image width in pixels. Only for image files                                                                                                                  |
| `messages[].files[].height`           | `number?`  | Image height in pixels. Only for image files                                                                                                                 |
| `messages[].archived`                 | `boolean?` | `true` only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with `GET /v1/conversations?mode=archive` |
| `hasMore`                             | `boolean`  | Whether a next page exists                                                                                                                                   |
| `cursor`                              | `string`   | Cursor for the next page. Included only when hasMore is true                                                                                                 |

#### Task Object

| Field            | Type      | Description                                                                                                                                                                                                                       |
| ---------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId`      | `string`  | ID of the message the task belongs to                                                                                                                                                                                             |
| `conversationId` | `string`  | ID of the conversation the task belongs to                                                                                                                                                                                        |
| `callId`         | `string?` | Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call                                                                                                       |
| `actionType`     | `string`  | Type of task (e.g., tool execution, code generation)                                                                                                                                                                              |
| `title`          | `string?` | Task title. Omitted when not present                                                                                                                                                                                              |
| `description`    | `string?` | Task description. Omitted when not present                                                                                                                                                                                        |
| `status`         | `string`  | Task status. One of: "in\_progress" / "completed" / "failed" / "error" / "pending"                                                                                                                                                |
| `content`        | `string?` | Task execution result text. Omitted when not present                                                                                                                                                                              |
| `metadata`       | `object?` | Auxiliary information that varies by actionType (sub\_event\_type, url, filepath, etc.). See the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md) for details |
| `files`          | `array?`  | Files related to the task (`filename` / `size` / `filepath` / `mimeType?`. `mimeType` is omitted when it cannot be determined). The array itself is omitted when there are no related files                                       |
| `timestamp`      | `number`  | Timestamp of task execution (Unix milliseconds)                                                                                                                                                                                   |
| `createdAt`      | `string`  | Creation date and time (ISO 8601)                                                                                                                                                                                                 |
| `updatedAt`      | `string`  | Last updated date and time (ISO 8601)                                                                                                                                                                                             |

<!-- -->

> **Safely ignore unknown fields**
>
> Future implementations may add new fields to `actionType` / `metadata`. Client implementations should safely ignore any fields not listed in this table. For detailed metadata structure, refer to the [Streaming Guide — Task data model](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md#task-data-model).

#### Response Example

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "sender": "User",
      "text": "Please analyze the sales data",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:30:00Z",
      "status": { "processing": false, "unfinished": false },
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### Pagination

Specify `limit` to fetch items in pages. While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

**Request example**

**curl**

```bash
# First page
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
-H "Authorization: Bearer <access_token>"

# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

If `limit` is omitted, 50 items are returned. To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

> **Using the cursor**
>
> The `cursor` represents a position in the result set. Do not change `order` while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
>
> Items may also be duplicated or skipped across pages if messages are added or removed while you are paging.

#### Error Response

| Status | code                      | Description                                                                                                                       |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted                            |
| `400`  | `invalid_parameter`       | limit is not an integer from 1 to 100, cursor is invalid (not a value from the previous response), or order is not "asc" / "desc" |
| `404`  | `conversation_not_found`  | The conversation was not found or is not yours                                                                                    |

<!-- -->

### PATCH`/v1/conversations/:conversationId`

Update the title of a conversation.

#### Path Parameters

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

#### Request Body

| パラメータ   | 型        | 必須 | 説明                                              |
| ------- | -------- | -- | ----------------------------------------------- |
| `title` | `string` | 必須 | New conversation title (200 characters or less) |

#### Request Example

**Update conversation**

**curl**

```curl
curl -X PATCH https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "title": "New title" }'
```

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
  json={"title": "New title"},
)

data = response.json()
print(f"Updated: {data['title']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "New title" }),
}
);

const data = await response.json();
console.log("Updated: " + data.title);
```

**Go**

```go
payload := map[string]string{"title": "New title"}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("PATCH",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

#### Response Fields (200 OK)

| Field            | Type     | Description                                                                           |
| ---------------- | -------- | ------------------------------------------------------------------------------------- |
| `conversationId` | `string` | Conversation ID (UUID)                                                                |
| `title`          | `string` | Updated title                                                                         |
| `type`           | `string` | Kind of conversation: "chat", "mail", or "project" (a conversation of a project step) |
| `createdAt`      | `string` | Creation timestamp (ISO 8601)                                                         |
| `updatedAt`      | `string` | Last update timestamp (ISO 8601)                                                      |

#### Response Example

```json
{
  "conversationId": "550e8400-...",
  "title": "New title",
  "type": "chat",
  "createdAt": "2026-03-14T10:30:00.000Z",
  "updatedAt": "2026-03-14T12:00:00.000Z"
}
```

#### Error Response

| Status | code                      | Description                                                                                            |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
| `400`  | `missing_parameter`       | title is missing                                                                                       |
| `400`  | `invalid_title`           | title is an empty string, is not a string, or exceeds 200 characters                                   |
| `400`  | `invalid_body`            | The body is malformed JSON                                                                             |
| `400`  | `conversation_archived`   | The conversation is archived                                                                           |
| `415`  | `unsupported_media_type`  | The Content-Type of the body is not application/json                                                   |
| `404`  | `conversation_not_found`  | The conversation was not found or is not yours                                                         |

### DELETE`/v1/conversations/:conversationId`

Delete a conversation. Of the files attached to its messages and its artifact files, those not used by any other conversation are deleted too (they no longer appear in `GET /v1/files`).

#### Path Parameters

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

#### Request Example

**Delete conversation**

**curl**

```curl
curl -X DELETE https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Deleted: {data['deleted']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Deleted: " + data.deleted);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field            | Type      | Description                           |
| ---------------- | --------- | ------------------------------------- |
| `conversationId` | `string`  | ID of the deleted conversation (UUID) |
| `deleted`        | `boolean` | Always true on successful deletion    |

#### Response Example

```json
{ "conversationId": "550e8400-...", "deleted": true }
```

#### Error Response

| Status | code                      | Description                                                                                            |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
| `400`  | `conversation_archived`   | The conversation is archived. Use `POST /v1/conversations/:id/restore` to restore it                   |
| `404`  | `conversation_not_found`  | The conversation was not found or is not yours                                                         |
| `409`  | `conversation_processing` | The conversation cannot be deleted because it is currently being processed                             |
| `409`  | `project_conversation`    | A project conversation. Project conversations cannot be deleted                                        |
| `409`  | `legal_hold`              | A conversation under legal hold. It cannot be deleted until an administrator releases the hold         |

### POST`/v1/conversations/:conversationId/restore`

Restore an archived conversation back to active. After restoration, the conversation can be edited, continued, and deleted just like a regular conversation.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                     |
| ---------------- | -------- | -- | -------------------------------------- |
| `conversationId` | `string` | 必須 | ID of the archived conversation (UUID) |

#### Request Example

**Restore archived conversation**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Restored: {data['restored']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Restored: " + data.restored);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field            | Type      | Description                             |
| ---------------- | --------- | --------------------------------------- |
| `conversationId` | `string`  | ID of the restored conversation (UUID)  |
| `restored`       | `boolean` | Always `true` on successful restoration |

#### Response Example

```json
{ "conversationId": "550e8400-...", "restored": true }
```

#### Error Response

| Status | code                      | Description                                                                                                      |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted           |
| `404`  | `conversation_not_found`  | The conversation does not exist in the archive, or is already active (not distinguished from the archived state) |

### POST`/v1/conversations/:conversationId/read`

Marks a conversation as read. Reading the messages of a conversation through the API (REST, MCP, or A2A) does not mark it as read, so call this when you want to record that it was read. The read position never moves back (specifying an earlier message does not move it before where it is).

<!-- -->

#### Path Parameters

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

#### Request Body (optional)

The body can be omitted. When you send one, use `Content-Type: application/json`.

| パラメータ       | 型        | 必須 | 説明                                                                                                                                                                                                 |
| ----------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId` | `string` | —  | ID of the last message you read. If omitted, the conversation is marked as read up to its latest message at that moment (specify it to avoid marking messages that arrived while you were reading) |

#### Request Example

**Mark a conversation as read**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/read \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"messageId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'
```

#### Response (204 No Content)

There is no body.

#### Error Responses

| Status | code                      | Description                                                                                            |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
| `400`  | `invalid_parameter`       | messageId is empty or not a string                                                                     |
| `400`  | `invalid_body`            | The body is not a JSON object                                                                          |
| `400`  | `conversation_archived`   | The conversation is archived                                                                           |
| `415`  | `unsupported_media_type`  | The body is not application/json                                                                       |
| `404`  | `conversation_not_found`  | The conversation does not exist or is not yours                                                        |
| `404`  | `message_not_found`       | The messageId is not in that conversation                                                              |

## File Management

Upload, retrieve, and delete files.

### Endpoint List

| メソッド   | エンドポイント                     | 説明              | Scope (SaaS) |
| ------ | --------------------------- | --------------- | ------------ |
| GET    | `/v1/files`                 | List files      | `chat:file`  |
| POST   | `/v1/files`                 | Upload a file   | `chat:file`  |
| GET    | `/v1/files/:fileId/content` | Download a file | `chat:file`  |
| DELETE | `/v1/files/:fileId`         | Delete a file   | `chat:file`  |

Note: The Marketplace edition does not require scopes (authentication only).

### POST`/v1/files`

Upload a file.

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

| パラメータ      | 型        | 必須 | 説明                                       |
| ---------- | -------- | -- | ---------------------------------------- |
| `file`     | `file`   | 必須 | The file to upload. Maximum size 512 MB. |
| `filename` | `string` | 必須 | File name                                |

#### Request Example

**Upload file**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/files \
-H "Authorization: Bearer <access_token>" \
-F "file=@report.pdf" \
-F "filename=report.pdf"
```

**Python**

```python
import requests

with open("report.pdf", "rb") as f:
  response = requests.post(
      "https://<your-domain>/api/v1/files",
      headers={"Authorization": f"Bearer {token}"},
      files={"file": f},
      data={"filename": "report.pdf"},
  )
  data = response.json()
  print(data["fileId"])
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("file", file); // File object from input
formData.append("filename", "report.pdf");

const response = await fetch(
"https://<your-domain>/api/v1/files",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
  body: formData,
}
);

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

**Go**

```go
file, _ := os.Open("report.pdf")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "report.pdf")
io.Copy(part, file)
writer.WriteField("filename", "report.pdf")
writer.Close()

req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/files",
  body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
```

#### Response Fields (201 Created)

| Field       | Type      | Description                                 |
| ----------- | --------- | ------------------------------------------- |
| `fileId`    | `string`  | Unique identifier of the file (UUID)        |
| `filename`  | `string`  | File name                                   |
| `bytes`     | `integer` | File size (bytes)                           |
| `createdAt` | `string`  | Creation date and time (ISO 8601)           |
| `width`     | `integer` | Image width (pixels). Only for image files  |
| `height`    | `integer` | Image height (pixels). Only for image files |

#### Response Example

```json
{
  "fileId": "550e8400-e29b-41d4-a716-446655440001",
  "filename": "report.pdf",
  "bytes": 1048576,
  "createdAt": "2026-03-14T10:30:00.000Z"
}
```

#### Error Response

| Status | code                              | Description                                                                                                                                           |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `missing_parameter`               | The file or filename parameter is missing                                                                                                             |
| `400`  | `file_too_large`                  | The file size exceeds 512 MB                                                                                                                          |
| `400`  | `invalid_parameter`               | The uploaded image file is corrupted or invalid                                                                                                       |
| `415`  | `unsupported_media_type`          | The body is not multipart/form-data, or the file type is not accepted (including extensions and MIME types the environment has decided not to accept) |
| `403`  | `feature_not_permitted`           | An administrator has not permitted file uploads                                                                                                       |
| `503`  | `feature_permissions_unavailable` | The feature permissions could not be checked. Retry after a while                                                                                     |

### GET`/v1/files`

List files. Cursor-based pagination is supported.

#### Query Parameters

| パラメータ    | 型         | 必須 | デフォルト    | 説明                                                                            |
| -------- | --------- | -- | -------- | ----------------------------------------------------------------------------- |
| `limit`  | `integer` | —  | `50`     | Number of items per page (1-100)                                              |
| `cursor` | `string`  | —  | —        | Cursor for the next page (the cursor value from the previous response)        |
| `order`  | `string`  | —  | `"desc"` | "asc" (oldest first) or "desc" (newest first). Sorted by the file update time |

#### Request Example

**List files**

**curl**

```curl
curl https://<your-domain>/api/v1/files?order=desc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/files",
  headers={"Authorization": f"Bearer {token}"},
  params={"order": "desc"},
)

files = response.json()["files"]
for file in files:
  print(f"{file['filename']} ({file['bytes']} bytes)")
```

**TypeScript**

```typescript
const params = new URLSearchParams({ order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/files?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.files.forEach((file) => {
console.log(file.filename + " (" + file.bytes + " bytes)");
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files?order=desc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field               | Type      | Description                                                  |
| ------------------- | --------- | ------------------------------------------------------------ |
| `files`             | `array`   | Array of file objects                                        |
| `files[].fileId`    | `string`  | Unique identifier of the file (UUID)                         |
| `files[].filename`  | `string`  | File name                                                    |
| `files[].bytes`     | `integer` | File size (bytes)                                            |
| `files[].createdAt` | `string`  | Creation date and time (ISO 8601)                            |
| `files[].width`     | `integer` | Image width (pixels). Only for image files                   |
| `files[].height`    | `integer` | Image height (pixels). Only for image files                  |
| `hasMore`           | `boolean` | Whether a next page exists                                   |
| `cursor`            | `string`  | Cursor for the next page. Included only when hasMore is true |

#### Response Example

```json
{
  "files": [
    {
      "fileId": "550e8400-e29b-41d4-a716-446655440001",
      "filename": "report.pdf",
      "bytes": 1048576,
      "createdAt": "2026-03-14T10:30:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Pagination

Specify `limit` to fetch items in pages. While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

**Request example**

**curl**

```bash
# First page
curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \
-H "Authorization: Bearer <access_token>"

# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

If `limit` is omitted, 50 items are returned. To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

> **Using the cursor**
>
> The `cursor` represents a position in the result set. Do not change `order` while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
>
> Items may also be duplicated or skipped across pages if files are added or removed while you are paging.

#### Error Response

| Status | code                | Description                                                |
| ------ | ------------------- | ---------------------------------------------------------- |
| `400`  | `invalid_parameter` | limit is not an integer from 1 to 100                      |
| `400`  | `invalid_parameter` | cursor is invalid (not a value from the previous response) |
| `400`  | `invalid_parameter` | order is not "asc" / "desc"                                |

### GET`/v1/files/:fileId/content`

Download a file.

#### Path Parameters

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

#### Request Example

**Download file**

**curl**

```curl
curl https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \
-H "Authorization: Bearer <access_token>" \
-o downloaded_file.pdf
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
  headers={"Authorization": f"Bearer {token}"},
  stream=True,
)

with open("downloaded_file.pdf", "wb") as f:
  for chunk in response.iter_content(chunk_size=8192):
      f.write(chunk)
```

**TypeScript**

```typescript
const fs = require("fs");
const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const buffer = await response.arrayBuffer();
fs.writeFileSync("downloaded_file.pdf", new Uint8Array(buffer));
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

file, _ := os.Create("downloaded_file.pdf")
defer file.Close()
io.Copy(file, resp.Body)
```

#### Response (200 OK)

The file binary data is returned as a stream.

| Response Header       | Description                                                                          |
| --------------------- | ------------------------------------------------------------------------------------ |
| `Content-Type`        | MIME type of the file                                                                |
| `Content-Length`      | File size (bytes)                                                                    |
| `Content-Disposition` | attachment; filename="filename"; filename\*=UTF-8''\<percent-encoded UTF-8 filename> |

When saving the file, use the name in `filename*` (the UTF-8 name, percent-encoded) if it is present; otherwise use `filename`. For a name that contains characters such as Japanese, `filename` is a substitute name, and the original name is only in `filename*`. For example, for `売上.pdf` ("sales.pdf" in Japanese), the header looks like this (the substitute name in `filename` is only an example).

```text
Content-Disposition: attachment; filename="file_1731650000000.pdf"; filename*=UTF-8''%E5%A3%B2%E4%B8%8A.pdf
```

#### Error Response

| Status | code                  | Description                                                                                                               |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`   | fileId has an invalid format                                                                                              |
| `404`  | `file_not_found`      | The file was not found                                                                                                    |
| `503`  | `service_unavailable` | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |

### DELETE`/v1/files/:fileId`

Delete a file. Deleting a conversation also deletes the files used only by that conversation (see [Delete a conversation](#delete-conversation)).

#### Path Parameters

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

#### Request Example

**Delete file**

**curl**

```curl
curl -X DELETE https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"File deleted: {data['deleted']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("File deleted: " + data.deleted);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field     | Type      | Description                        |
| --------- | --------- | ---------------------------------- |
| `fileId`  | `string`  | ID of the deleted file (UUID)      |
| `deleted` | `boolean` | Always true on successful deletion |

#### Response Example

```json
{ "fileId": "550e8400-e29b-41d4-a716-446655440001", "deleted": true }
```

#### Error Response

| Status | code                | Description                  |
| ------ | ------------------- | ---------------------------- |
| `400`  | `invalid_parameter` | fileId has an invalid format |
| `404`  | `file_not_found`    | The file was not found       |

## Artifact Retrieval

Retrieve artifact files generated by the agent.

### Endpoint List

| メソッド | エンドポイント           | 説明                   | Scope (SaaS) |
| ---- | ----------------- | -------------------- | ------------ |
| GET  | `/v1/files/proxy` | Get an artifact file | `chat:exec`  |

Note: The Marketplace edition does not require scopes (authentication only).

### GET`/v1/files/proxy`

Download an artifact file by specifying the path obtained from `deliverables[].filepath` in the message history.

<!-- -->

The Marketplace edition does not enforce scopes. Any authenticated token can download artifacts.

<!-- -->

<!-- -->

#### Query Parameters

| パラメータ  | 型        | 必須 | 説明                                                                                 |
| ------ | -------- | -- | ---------------------------------------------------------------------------------- |
| `path` | `string` | 必須 | Artifact file path (obtained from deliverables\[].filepath in the message history) |

#### Request Example

`filepath` is the value of `messages[].deliverables[].filepath` from [Get message history](#get-messages).

**Get artifact file**

**curl**

```curl
FILEPATH='<filepath>'

curl --get "https://<your-domain>/api/v1/files/proxy" \
--data-urlencode "path=$FILEPATH" \
-H "Authorization: Bearer <access_token>" \
-o artifact.xlsx
```

**Python**

```python
import requests

filepath = "<filepath>"

response = requests.get(
  "https://<your-domain>/api/v1/files/proxy",
  headers={"Authorization": "Bearer " + token},
  params={"path": filepath},
  stream=True,
)

with open("artifact.xlsx", "wb") as f:
  for chunk in response.iter_content(chunk_size=8192):
      f.write(chunk)
```

**TypeScript**

```typescript
const filepath = "<filepath>";

const params = new URLSearchParams({
path: filepath,
});
const response = await fetch(
"https://<your-domain>/api/v1/files/proxy?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const blob = await response.blob();
```

**Go**

```go
import (
  "io"
  "net/http"
  "net/url"
  "os"
)

filepath := "<filepath>"

req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files/proxy?"+url.Values{"path": {filepath}}.Encode(),
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

out, _ := os.Create("artifact.xlsx")
defer out.Close()
io.Copy(out, resp.Body)
```

#### Response (200 OK)

The artifact file binary data is returned as a stream.

| Response Header  | Description           |
| ---------------- | --------------------- |
| `Content-Type`   | MIME type of the file |
| `Content-Length` | File size (bytes)     |

#### Error Response

| Status | code                  | Description                                                                                                               |
| ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `missing_parameter`   | The path parameter is missing                                                                                             |
| `400`  | `invalid_parameter`   | The path format is invalid (no UUID-shaped segment)                                                                       |
| `404`  | `not_found`           | The file was not found (if the storage response carries another code, that code is returned)                              |
| `500`  | `unknown`             | Unknown error from the storage                                                                                            |
| `500`  | `storage_forbidden`   | Access to the storage was denied. Contact your administrator                                                              |
| `500`  | `rejected`            | The storage rejected the request. Contact your administrator                                                              |
| `503`  | `rate_limited`        | The storage is temporarily busy. Retry after a while                                                                      |
| `503`  | `transient`           | The storage is temporarily unavailable. Retry after a while                                                               |
| `503`  | `service_unavailable` | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |

## Search

Full-text search messages.

### Endpoint List

| メソッド | エンドポイント               | 説明                        | Scope (SaaS)   |
| ---- | --------------------- | ------------------------- | -------------- |
| GET  | `/v1/search/messages` | Full-text search messages | `chat:history` |

Note: The Marketplace edition does not require scopes (authentication only).

### GET`/v1/search/messages`

Full-text search messages. Messages of conversations of project steps and of archived conversations are not searched. Results are returned newest first by creation time (oldest first with `order=asc`), with cursor-based pagination.

#### Query Parameters

| パラメータ    | 型         | 必須 | 説明                                                                                                           |
| -------- | --------- | -- | ------------------------------------------------------------------------------------------------------------ |
| `q`      | `string`  | 必須 | Search query                                                                                                 |
| `order`  | `string`  | —  | Sort order. "asc" (ascending) or "desc" (descending, default)                                                |
| `limit`  | `integer` | —  | Number of items per page (1-100). Defaults to 50.                                                            |
| `cursor` | `string`  | —  | Cursor value for the next page. Pass the cursor from the previous response as is, with the same q and order. |

#### Request Example

**Search messages**

**curl**

```curl
curl "https://<your-domain>/api/v1/search/messages?q=sales" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests
from urllib.parse import quote

query = "sales"
response = requests.get(
  "https://<your-domain>/api/v1/search/messages",
  headers={"Authorization": f"Bearer {token}"},
  params={"q": query, "order": "desc"},
)

messages = response.json()["messages"]
for msg in messages:
  print(f"{msg['title']}: {msg['text'][:50]}")
```

**TypeScript**

```typescript
const query = "sales";
const params = new URLSearchParams({ q: query, order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/search/messages?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.messages.forEach((msg) => {
console.log(msg.title + ": " + msg.text);
});
```

**Go**

```go
query := "sales"
req, _ := http.NewRequest("GET",
  fmt.Sprintf("https://<your-domain>/api/v1/search/messages?q=%s&order=desc",
      url.QueryEscape(query)),
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field                                 | Type      | Description                                                                                                                                                                                                                                                  |
| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `messages`                            | `array`   | Array of search result messages (one page, up to limit)                                                                                                                                                                                                      |
| `messages[].conversationId`           | `string`  | Conversation ID (UUID)                                                                                                                                                                                                                                       |
| `messages[].messageId`                | `string`  | Unique identifier of the message                                                                                                                                                                                                                             |
| `messages[].text`                     | `string`  | Message body text                                                                                                                                                                                                                                            |
| `messages[].title`                    | `string`  | Conversation title                                                                                                                                                                                                                                           |
| `messages[].sender`                   | `string`  | Sender. "User" or "AI"                                                                                                                                                                                                                                       |
| `messages[].createdAt`                | `string`  | Creation date and time (ISO 8601)                                                                                                                                                                                                                            |
| `messages[].updatedAt`                | `string`  | Last updated date and time (ISO 8601)                                                                                                                                                                                                                        |
| `messages[].matchedQueries`           | `array`   | Array of matched search queries                                                                                                                                                                                                                              |
| `messages[].status`                   | `object`  | Message processing status                                                                                                                                                                                                                                    |
| `messages[].status.processing`        | `boolean` | Whether the agent is currently processing                                                                                                                                                                                                                    |
| `messages[].status.unfinished`        | `boolean` | Whether the agent response was interrupted                                                                                                                                                                                                                   |
| `messages[].tasks`                    | `array`   | Array of tasks executed by the agent. See the Task object under [GET /v1/conversations/:conversationId/messages](#get-messages) for field definitions                                                                                                        |
| `messages[].deliverables`             | `array`   | Array of artifacts generated by the agent (included only when present)                                                                                                                                                                                       |
| `messages[].deliverables[].filename`  | `string`  | Artifact file name                                                                                                                                                                                                                                           |
| `messages[].deliverables[].filepath`  | `string`  | Artifact file path                                                                                                                                                                                                                                           |
| `messages[].deliverables[].source`    | `string`  | `"agent"` (agent-generated) or `"user"` (user-uploaded)                                                                                                                                                                                                      |
| `messages[].deliverables[].isPrimary` | `boolean` | Whether it is a primary artifact                                                                                                                                                                                                                             |
| `messages[].deliverables[].createdAt` | `string`  | Creation date and time (ISO 8601 format). An empty string when unknown                                                                                                                                                                                       |
| `messages[].deliverables[].mimeType`  | `string`  | MIME type (e.g., `"application/pdf"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined                                                                                                                                          |
| `messages[].deliverables[].size`      | `number?` | File size (bytes). Omitted when 0 or below                                                                                                                                                                                                                   |
| `messages[].files`                    | `array?`  | Array of user-uploaded files. Included only when present for messages with `sender: "User"`. The field structure matches the history API (`fileId` / `mimeType` / `width?` / `height?`). See [GET /v1/conversations/:id/messages](#get-messages) for details |
| `hasMore`                             | `boolean` | true when there is a next page. When true, cursor is returned                                                                                                                                                                                                |
| `cursor`                              | `string`  | Cursor value for the next page. Included only when hasMore is true                                                                                                                                                                                           |
| `limitReached`                        | `boolean` | true only when many messages match and only the most relevant results (up to 1,000 each for matches in the message text and in the agent's task progress) are covered. Not included otherwise. To search exhaustively, narrow the query                      |

#### Response Example

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "text": "Result of sales data analysis...",
      "title": "Sales data analysis",
      "sender": "AI",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z",
      "matchedQueries": ["sales"],
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### Error Response

| Status | Description                                                                                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | q parameter is missing or not a single string (for example, q specified more than once), order is not "asc" / "desc", limit is not an integer from 1 to 100, or cursor cannot be read |
| `501`  | An environment where search is not configured (`code: "search_not_configured"`)                                                                                                       |
| `503`  | Search is temporarily unavailable (`code: "service_unavailable"`). Retry after a while                                                                                                |

## Projects

A project is the unit in which multiple agents are placed to carry out work. From an external system you can list projects, start a run<!-- -->, check run status, and get the artifacts of workflow runs<!-- -->.

There are two project types, and each is triggered differently.

| Type       | Description                                                                                           | How runs are triggered                                    |
| ---------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `workflow` | Advances through steps in order. A run starts from the first enabled step.                            | `POST /v1/projects/{projectId}/runs`                      |
| `cycle`    | Keeps multiple agents running on their own schedules. An external event can add one extra ad-hoc run. | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire` |

> **What you can operate on**
>
> With a service account token, you can operate on every project in this environment. An application (sign-in from an external tool) token can also call the nine endpoints here and the other project APIs. What it can operate on then depends on how the user participates in the project and on the organization operations role ([User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md)). Calling them with a user token obtained in any other way returns `404 Not Found` for every endpoint.

### Endpoints

| メソッド | エンドポイント                                                    | 説明                                                  |
| ---- | ---------------------------------------------------------- | --------------------------------------------------- |
| GET  | `/v1/projects`                                             | List projects                                       |
| POST | `/v1/projects/{projectId}/runs`                            | Start a project run                                 |
| POST | `/v1/projects/{projectId}/triggers/{triggerId}/fire`       | Fire a trigger for one ad-hoc run                   |
| GET  | `/v1/projects/{projectId}/runs/{runId}`                    | Get run status                                      |
| POST | `/v1/projects/{projectId}/runs/{runId}/cancel`             | Cancel a workflow run                               |
| POST | `/v1/projects/{projectId}/executions/{executionId}/cancel` | Stop a sweep execution of a cycle project           |
| GET  | `/v1/projects/{projectId}/executions/{executionId}`        | Get the status of an execution (status fields only) |
| 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 (HEAD also works)    |

### GET`/v1/projects`

Retrieves the list of all projects in this environment.<!-- --> 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) |

Any other query parameter is ignored.

<!-- -->

#### Request Example

**List projects**

**curl**

```curl
curl "https://<your-domain>/api/v1/projects?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field                  | Type      | Description                                                                                            |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `projects`             | `array`   | Array of project objects                                                                               |
| `projects[].projectId` | `string`  | Project ID (UUID)                                                                                      |
| `projects[].name`      | `string`  | Project name                                                                                           |
| `projects[].type`      | `string`  | "workflow" or "cycle"                                                                                  |
| `projects[].status`    | `string`  | Project state. One of "active", "paused", "archived" or "admin\_stopped" (stopped by an administrator) |
| `projects[].tags`      | `array`   | Array of tags. An empty array when none are set                                                        |
| `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": []
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Always-on inquiry handling",
      "type": "cycle",
      "status": "active",
      "tags": []
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                                                              |
| ------ | ------------------------------------------------------------------------ |
| `400`  | limit is outside 1-100 or cursor is invalid (code is invalid\_parameter) |

### 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 those 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                                                                                                                                                                                                  |
| `config`  | `object` | —  | Input files and step settings. Write one entry per placement and step, in the form { "placements": \[{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] }. fileBindings maps input file names (inputs\[].name from the list of registered Agents that can be placed) to the artifactId of uploaded drafts; parameters are the registered Agent's parameters (in the shape of parametersSchema); connectionBindings maps connection slot names to connector IDs. All fields other than placementId and stepId can be omitted. Omitted or null means no settings |

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.

`config` also counts toward the 16 KiB limit of the whole body.

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

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

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

#### Request Example

**Start run**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

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

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

#### Response Example

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

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

Resending with the same key but a different `payload` or `config` 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `404`  | `project_not_found`               | The project does not exist or is not accessible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `400`  | `approvers_required`              | An enabled review step has no reviewers configured                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `unsupported_project_type`        | A cycle project was specified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `409`  | `project_inactive`                | The project is not active (paused or archived)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `409`  | `principal_suspended`             | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `409`  | `start_step_in_branch_lane`       | The start step is in a lane of a branch step. Set the start step of the time trigger to a step outside the lanes of branch steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `definition_pending`              | The first definition of the project is waiting for approval, so it cannot run yet. Start it after an approver (another owner or an administrator of the organization) approves it in the product screen                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `409`  | `relink_required`                 | The project cannot be started or resumed until the references that were not found during import are reconnected. The remaining references appear in the project's relink and in the placements' relink. To clear the references that refuse a start: for rows whose kind is "agent", place the agent again (POST /v1/projects/{projectId}/placements); for rows whose kind is "connector", save the connector again on the product screen. Rows whose blocking is false are items to set up again if needed and do not refuse runs; they can be cleared with DELETE /v1/projects/{projectId}/relink, but clearing them alone does not make the project startable |
| `409`  | `admin_stopped`                   | An administrator has stopped the project, or a registered agent placed in it. Ask an administrator to resume it (this API cannot resume it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `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`                  | config is malformed, names a placement or step that does not exist, does not match the registered Agent definition, or the project has no registered Agents placed on its steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `409`  | `artifact_not_ready`              | An artifact specified as an input is not ready yet (or differs from the content that was reviewed). With a system integration token, only drafts that a current owner of the project uploaded and that are not yet bound to a run can be specified                                                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `origin_conflict`                 | A different payload or config 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

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

#### Request Example

**Fire trigger**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

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

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

#### Response Fields (202 Accepted)

| Field         | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `result`      | `string` | "accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `jobId`       | `string` | ID of the receiving job. It 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})                                                                                                                                                                                                                                                                                       |
| `executionId` | `string` | ID of the accepted sweep execution. It can be used to get the result of the execution and to stop the sweep execution. A resend with the same eventId returns the same value (it can be missing from the response to a resend; then find the execution as described in Finding the Execution Started by a Fire). Until it starts (this can take about a minute, and longer when earlier fires to the same step of the same agent placement are waiting), getting the result of the execution returns 404 Not Found (execution\_not\_found) |

#### Response Example

<!-- -->

<!-- -->

```json
{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40",
  "executionId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
```

> **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                                                                                |
| `404`  | `trigger_not_found`      | The project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified                   |
| `409`  | `trigger_disabled`       | The trigger is disabled                                                                                                                               |
| `409`  | `project_not_active`     | The project is not in a runnable state                                                                                                                |
| `409`  | `principal_suspended`    | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension |
| `409`  | `admin_stopped`          | An administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it                           |
| `409`  | `placement_unavailable`  | The target agent placement does not exist, 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)                                            |

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

#### Request Example

**Get run**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

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

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

#### Response Fields (200 OK)

| Field                             | Type             | Description                                                                                                                                                                                                                                                                               |
| --------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`                           | `string`         | Run ID (UUID)                                                                                                                                                                                                                                                                             |
| `status`                          | `string`         | Run state. One of "running" (running), "waiting\_gate" (awaiting review), "closed\_done" (completed), "closed\_rejected" (ended by rejection), "closed\_failed" (ended by failure) or "cancelled" (cancelled). Any value other than "running" and "waiting\_gate" means the run has ended |
| `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. "branch\_undecided" when a branch could not decide and a person is asked to choose; "branch\_not\_selected" for a step in a lane the branch did not choose                                                                                                    |
| `steps[].held`                    | `boolean`        | Whether the step is held because the project is paused and is waiting to resume                                                                                                                                                                                                           |
| `steps[].visit`                   | `number \| null` | Which visit to this step this is (increases with send-backs). null for rows without this record                                                                                                                                                                                           |
| `steps[].reworkReason`            | `string \| null` | Reason for the send-back                                                                                                                                                                                                                                                                  |
| `steps[].gateFor`                 | `string \| null` | For a review row, the step run (runStepId) it was raised for                                                                                                                                                                                                                              |
| `steps[].routedFrom`              | `string \| null` | When steps were skipped by choosing a destination, the step run (runStepId) that chose it                                                                                                                                                                                                 |
| `steps[].late`                    | `string \| null` | Why a result that arrived late was not used to advance the run                                                                                                                                                                                                                            |
| `steps[].gate`                    | `object \| null` | Summary of the review. Set on review step rows. 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                                                                                                                                                                                                                                                                     |

<!-- -->

##### 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": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "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 |

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

Cancels a workflow run that is running or awaiting review (`status` is `"running"` or `"waiting_gate"`). This is the same as Cancel run on the screen.

When it is cancelled:

- The `status` of the workflow run becomes `"cancelled"` (cancelled).
  <!-- -->
  This cannot be undone.
- <!-- -->
  Steps that have not started are not started. The Agents of running steps are told to stop (the status of such a step row may not change until it stops).
  <!-- -->
- Review requests of review steps that have not been decided are withdrawn.

#### Path Parameters

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

#### Request Body

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

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

#### Request Example

**Cancel run**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

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

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

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

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

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

#### Response Example

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

#### Error Responses

| Status | code                     | Description                                                                                                                              |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or runId is not a UUID, commandId is missing or has the wrong form, or reason is not a string or is longer than 500 characters |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                          |
| `404`  | `run_not_found`          | The workflow run does not exist, belongs to another project, or the project is not accessible                                            |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                  |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                     |

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

For a cycle project, stops a sweep execution. This is the same as Stop on the screen. <!-- -->No body is needed (a body is not used even if sent).

- Only sweep executions of cycle projects can be stopped. Specifying an execution of a workflow step (`rs:<number>`) returns `400 Bad Request` (`invalid_parameter`). To stop a workflow run, use [Cancel a Workflow Run](#cancel-run).
- After it is accepted, it can take about a minute for the execution to stop. Check whether it stopped with Get the Result of an Execution (`GET /v1/projects/{projectId}/executions/{executionId}`). It can also be called with a system integration (service account) token (it returns only the status fields). An execution that had not started yet when the stop request was accepted stays `404 Not Found` (`execution_not_found`) in Get the Result of an Execution.
- For an execution whose stop was already requested, or that had already ended, nothing changes: `200 OK` is returned with `existing` set to `true`.

#### Path Parameters

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

#### Request Example

**Cancel execution**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

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

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

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

`202 Accepted` when a new stop request was accepted, and `200 OK` otherwise.

| Field         | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executionId` | `string`  | ID of the execution                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `state`       | `string`  | The state when the request was accepted. It does not indicate whether the execution actually stopped (see the first bullet of this section for how to check). Example values: "dispatched" (the stop request was passed to the running execution), "cancelled" (an execution that had not started yet was cancelled), "terminal" (the execution had already finished). Other state values of the execution or the dispatch at the time of acceptance may also be returned as they are. Do not fix a list of values and rely on it |
| `existing`    | `boolean` | true when a stop had already been requested or the execution had already ended (always false with 202 Accepted)                                                                                                                                                                                                                                                                                                                                                                                                                   |

#### Response Example

```json
{
  "executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "state": "dispatched",
  "existing": false
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId is not a UUID, executionId is neither rs:\<number> nor a UUID, or executionId is an execution of a workflow step |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                            |
| `404`  | `execution_not_found`    | The execution does not exist, belongs to another project, the project is not a cycle, or the project is not accessible     |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                    |
| `415`  | `unsupported_media_type` | A request body is sent with a Content-Type other than application/json                                                     |

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

Gets the status of an execution (whether it is running, whether it has ended, and how it ended). With a service account token, it returns only the status fields below. Called with an application (sign-in from an external tool) token, it returns the same fields as Get the Result of an Execution in the [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md#get-execution).

- A sweep execution of a cycle project can be read with `executionId` in the response of a trigger fire. Until it starts (this can take about a minute), it returns `404 Not Found` (`execution_not_found`). Use it also to check whether a sweep execution stopped after you stopped it.
- An execution of a workflow step can be read with `steps[].executionId` (a UUID) of the workflow run. `executionId` in the response is `rs:<number>`, and an ID in this form can also be used.

#### Path Parameters

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

#### Request Example

**Get execution status**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

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

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

#### Response Fields (200 OK)

The fields returned when called with a service account token.

| Field         | Type             | Description                                                                                                                                                                                                 |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executionId` | `string`         | Execution ID. rs:\<number> for a workflow, and a UUID for a cycle                                                                                                                                           |
| `kind`        | `string \| null` | "run\_step" (a workflow step) or "sweep" (a cycle sweep)                                                                                                                                                    |
| `runId`       | `string \| null` | ID of the workflow run. null for a cycle                                                                                                                                                                    |
| `stepId`      | `string \| null` | Step ID                                                                                                                                                                                                     |
| `placementId` | `string \| null` | Placement ID                                                                                                                                                                                                |
| `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)                                                                         |
| `outcome`     | `string \| null` | Outcome (see [Outcome Values](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md#execution-outcomes) in the User API Reference (Projects))   |
| `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                                                    |
| `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) |
| `terminal`    | `boolean`        | Whether it has finished                                                                                                                                                                                     |
| `startedAt`   | `string \| null` | Start time (ISO 8601)                                                                                                                                                                                       |
| `endedAt`     | `string \| null` | End time (ISO 8601)                                                                                                                                                                                         |

#### Error Responses

| Status | code                  | Description                                                                                                                               |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`   | projectId is not a UUID, or executionId is neither rs:\<number> nor a UUID                                                                |
| `404`  | `execution_not_found` | The execution does not exist, belongs to another project, is a sweep execution that has not started yet, or the project is not accessible |

#### Response Example

```json
{
  "executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "kind": "sweep",
  "runId": null,
  "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
  "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "attempt": 1,
  "outcome": "completed",
  "reasonCode": null,
  "resultState": "terminal",
  "terminal": true,
  "startedAt": "2026-11-18T01:30:05.000Z",
  "endedAt": "2026-11-18T01:34:40.000Z"
}
```

<!-- -->

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

Gets all artifacts of a workflow run (the input files bound at the start and the outputs made by the steps), 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`). <!-- -->With a service account token, you can read the artifacts of every project in this environment. `run_id` is required.

#### Path Parameters

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

#### Query Parameters

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

#### Request Example

**List run artifacts**

**curl**

```curl
curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts",
  headers={"Authorization": f"Bearer {token}"},
  params={"run_id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13"},
)

with open("artifact.bin", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts" + "?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### 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)                     |
| `hasMore`                | `boolean`        | Always false (all artifacts are returned)                 |

#### Response Example

```json
{
  "artifacts": [
    {
      "artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
      "name": "report.md",
      "mimeType": "text/markdown",
      "size": 2048,
      "status": "ready",
      "createdAt": "2026-11-18T05:30:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | code                | Description                                                    |
| ------ | ------------------- | -------------------------------------------------------------- |
| `400`  | `invalid_parameter` | projectId is not a UUID, or run\_id is missing or not a UUID   |
| `404`  | `project_not_found` | The project does not exist                                     |
| `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).<!-- --> When read with a service account token, it is recorded as the system integration.

#### Path Parameters

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

#### Request Example

**Get run artifact content**

**curl**

```curl
curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content",
  headers={"Authorization": f"Bearer {token}"},
)

with open("artifact.bin", "wb") as f:
  f.write(response.content)
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### 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                                                                                           |
| `404`  | `artifact_not_found` | The project or the artifact does not exist, the artifact belongs to another project, or it is not an artifact of a workflow run |
| `409`  | `artifact_not_ready` | The artifact is not fully written yet                                                                                           |

### Notes on the Project API

| Item                          | Detail                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What 404 means                | The same `404 Not Found` is returned whether the project does not exist or is not accessible, and the response does not reveal which of the two applies. The code is fixed per endpoint: `project_not_found` for starting a run, `trigger_not_found` for firing a trigger, and `run_not_found` for run status and for canceling a workflow run. Listing artifacts returns `project_not_found` (`run_not_found` when the run does not exist), and getting the content of an artifact returns `artifact_not_found`. Stopping a sweep execution and getting the status of an execution return `execution_not_found`. |
| When the type is out of scope | Calling trigger fire on a `workflow` project, or run status or canceling a workflow run on a `cycle` project, returns `404`. Stopping a sweep execution on a `workflow` project also returns `404`. Starting a run on a `cycle` project is the one exception: it returns `409 unsupported_project_type`.                                                                                                                                                                                                                                                                                                          |
| Request body                  | When you send a body, make it a JSON object. Anything other than `Content-Type: application/json` returns `415`, malformed JSON or a body that is not a JSON object returns `400` (`invalid_body`), and a body larger than 16 KiB returns `413`.                                                                                                                                                                                                                                                                                                                                                                  |
| Unknown fields / queries      | Fields and query parameters that are not in the specification are ignored. An invalid value for a documented query parameter, or a `cursor` that cannot be read, returns `400 Bad Request`.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Timeouts                      | `504 Gateway Timeout` does not mean "it did not run". Resend a run start with the same `Idempotency-Key`, a trigger fire with the same `eventId` and the same body, and a workflow run cancel with the same `commandId`. A sweep execution stop can also be resent as it is.                                                                                                                                                                                                                                                                                                                                      |

## Error Responses

### HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

| Status                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | Invalid request parameters                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `401 Unauthorized`           | Token is invalid or missing. Also returned for a token of a user whose use was suspended by an administrator (see "Suspended users" below)                                                                                                                                                                                                                                                                                                               |
| `403 Forbidden`              | No access permission to the resource                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `404 Not Found`              | Resource does not exist, or the path or method is not defined (405 is not returned)                                                                                                                                                                                                                                                                                                                                                                      |
| `409 Conflict`               | Operation conflict, such as the resource currently being processed                                                                                                                                                                                                                                                                                                                                                                                       |
| `409 Conflict`               | A person with the organization operations role (the "Operator" role assigned in "Admin Roles" in the admin console) who does not take part in the project called an operation that role cannot use (`error.code` is `forbidden_role`). It does not clear by waiting. For an owner-only operation, ask an owner of the project to do it. For other operations, ask an owner to add you to the project; you can then call them as your project role allows |
| `413 Payload Too Large`      | Request body exceeds the size limit                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `415 Unsupported Media Type` | The request body format (Content-Type) is not supported                                                                                                                                                                                                                                                                                                                                                                                                  |
| `429 Too Many Requests`      | Rate limit or concurrent-run limit exceeded. `error.type` is `rate_limit_error`, and `error.code` depends on the endpoint (for example `monthly_quota_exceeded` for the monthly limit and `too_many_active_runs` for concurrent project runs). Please wait and retry.                                                                                                                                                                                    |
| `500 Internal Server Error`  | Internal server error                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `502 Bad Gateway`            | Communication error with upstream services (authentication / chat backends, etc.)                                                                                                                                                                                                                                                                                                                                                                        |
| `503 Service Unavailable`    | Service temporarily unavailable                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `504 Gateway Timeout`        | Upstream service response timeout                                                                                                                                                                                                                                                                                                                                                                                                                        |

### Error Response Format

All error responses are returned in the following common structure.

| Field                    | Type     | Description                                                                                                                                                                                                                                                        |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `error.type`             | `string` | Error classification. One of: "invalid\_request\_error", "authentication\_error", "insufficient\_scope\_error", "forbidden\_error", "not\_found\_error", "conflict\_error", "payload\_too\_large\_error", "rate\_limit\_error", "server\_error", "upstream\_error" |
| `error.message`          | `string` | Human-readable error message                                                                                                                                                                                                                                       |
| `error.code`             | `string` | Machine-processable error code (e.g., "missing\_parameter", "invalid\_parameter", "invalid\_token")                                                                                                                                                                |
| `error.param`            | `string` | The parameter that caused the error. Included only for validation errors                                                                                                                                                                                           |
| `error.reason`           | `string` | The kind of reason for the refusal. Included only for 409 (definition\_invalid) of the project APIs                                                                                                                                                                |
| `error.suggested_action` | `string` | Recommended action to take. Included only for some errors                                                                                                                                                                                                          |

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid parameter: limit",
    "code": "invalid_parameter",
    "param": "limit",
    "suggested_action": "limit must be between 1 and 100"
  }
}
```

### Suspended users

A call with the token of a user whose use was suspended by an administrator returns `401 Unauthorized`. `error.code` is `account_suspended`.

The following APIs do not check whether the user is suspended: `GET /v1/organizations`, `GET /v1/job-types`, `GET /v1/user`, `PATCH /v1/user`, `GET /v1/marketplace-agents`, the MCP tools `list_agents` and `cancel_chat` (when no task is in progress), and the Agent Card of a registered Agent (`GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json`).
