# システム連携 API リファレンス

マーケットプレイス版のシステム連携 API のエンドポイント仕様とエラーコードのリファレンスです。

> **注記**
>
> このページは、システム連携（サービスアカウント）のトークンで呼ぶ API のリファレンスです。システム連携で利用できるのは、チャット・会話管理・ファイル管理・成果物取得・検索・登録 Agent の一覧と、プロジェクトの 9 つの API（[プロジェクト](#projects)）です。アプリケーション（外部ツールでのログイン）のトークンで呼ぶ API は、[ユーザー API リファレンス（会話・組織）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference.md) と [ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md) を参照してください。ライブラリ・ライブラリの Agent・スキル・プレイブック・ペルソナ・ユーザー管理・ログ・共有メモリの各 API は SaaS 版でのみ提供されます。SaaS 版の仕様は [ユーザー API リファレンス（SaaS 版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md) と [システム連携 API リファレンス（SaaS 版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md) を参照してください。

## ベース URL

すべての API リクエストは以下のベース URL に対して送信します。`<your-domain>` は導入した環境のドメインに読み替えてください。

Marketplace

`https://<your-domain>/api`

本ドキュメントのエンドポイントパスはベース URL からの相対パスで記載しています。

## 認証

すべてのAPIリクエストには、`Authorization` ヘッダーに Bearer トークンを含める必要があります。

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

トークンが無効または未指定の場合、`401 Unauthorized` が返されます。マーケットプレイス版ではスコープによる制限はありません。

このページの API は、サービスアカウントのトークンで呼びます。アプリケーション（外部ツールでのログイン）のトークンで呼べる API は、ユーザー API リファレンスに載せています。外部ツールでのログイン以外で得た利用者のトークン（メイン画面にログインしたときのトークンなど）で呼ぶと、どのエンドポイントも `404 Not Found` が返ります。

トークンの取得方法については、[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md) および [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md) を参照してください。

> **チャット API の注意**
>
> マーケットプレイス版でチャット API を利用する場合、`agentId` パラメータが必須で、`stream: true` 固定で動作します。詳細は[API を呼び出す](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/quickstart/call-api.md)を参照してください。

## 共通の決まり

このページの API に共通の決まりです。

### リクエストの扱い

このページの API は、リクエストを次のように扱います。エンドポイントごとの扱いは、各エンドポイントの説明とエラーレスポンスを参照してください。

| 送ったもの                                                                                        | 扱い                                                                                  |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 仕様に無いクエリパラメータとボディのフィールド                                                                      | 無視されます。ただし、このページに載っていない項目でも、サービスが受け付けている項目は、型や値が正しくないと `400 Bad Request` になることがあります |
| 仕様にあるクエリパラメータの不正な値                                                                           | `400 Bad Request`                                                                   |
| パスパラメータの値の不正な URL エンコード（`%` の並び）                                                             | `400 Bad Request`（`invalid_parameter`）                                              |
| 壊れた JSON のボディ                                                                                | `400 Bad Request`（`invalid_body`）                                                   |
| JSON のボディを受け付けるエンドポイントへの、`Content-Type: application/json` 以外のボディ、対応していない文字コード（`charset`）のボディ | `415 Unsupported Media Type`（`unsupported_media_type`）                              |
| ファイルのアップロードへの、`multipart/form-data` 以外のボディ                                                   | `415 Unsupported Media Type`                                                        |
| 型の違うボディのフィールド                                                                                | `400 Bad Request`                                                                   |

ボディの読み取りで `400`（壊れた JSON など）や `413`（サイズの上限を超えたなど）になる場合は、`415` よりそちらが先に返ります。

<!-- -->

### ページネーション

一覧取得エンドポイントはカーソルベースのページネーションをサポートしています。

| パラメータ    | 型         | 説明                                                                                   |
| -------- | --------- | ------------------------------------------------------------------------------------ |
| `limit`  | `integer` | 1ページあたりの取得件数（1-100）。デフォルトは 50 件です                                                    |
| `cursor` | `string`  | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します                                   |
| `order`  | `string`  | ソート順。"asc"（昇順）または "desc"（降順、デフォルト）。ほかの値を指定すると 400 Bad Request が返ります。対応するエンドポイントは一部です |

レスポンスには `hasMore` フィールドが含まれます。`true` の場合、`cursor` の値を次のリクエストに渡すことで次ページを取得できます。

カーソルベースのページネーションに対応しているのは、[会話一覧](#conversations)・[メッセージ一覧](#conversations)・[ファイル一覧](#file-management)・[メッセージの検索](#search-messages)・[プロジェクト一覧](#projects) の各一覧エンドポイントです。`cursor` は不透明な値のため、内容を解釈せず、前回レスポンスの値をそのまま次のリクエストに指定してください。

## チャット

OpenAI互換のChat Completions APIです。エージェントとの対話はSSE（Server-Sent Events）ストリーミングで配信されます。

チャットAPIは3つのエンドポイントで構成されます。メッセージの送信、既存会話への再接続、進行中の会話のキャンセルが可能です。

SSE ストリーミングガイド

接続フロー・レスポンスオブジェクト・Delta拡張・実行パターン・再接続・エラーハンドリングの詳細解説

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md)

### エンドポイント一覧

| メソッド | エンドポイント                                       | 説明                                | スコープ (SaaS) |
| ---- | --------------------------------------------- | --------------------------------- | ----------- |
| POST | `/v1/chat/completions`                        | チャットメッセージを送信し、SSEストリーミングでレスポンスを取得 | `chat:exec` |
| GET  | `/v1/chat/completions/:conversationId`        | 進行中の会話のSSEストリームに再接続               | `chat:exec` |
| POST | `/v1/chat/completions/:conversationId/cancel` | 進行中の会話をキャンセル                      | `chat:exec` |

※ Marketplace 版はスコープ不要（認証のみ）。

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

エージェントにメッセージを送信し、SSEストリーミングでレスポンスを受け取ります。レスポンスはOpenAI互換のChat Completion Chunk形式で配信されます。

#### リクエストヘッダー

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

#### リクエストボディ

| パラメータ            | 型         | 必須 | 説明                                                                                                                                                                                       |
| ---------------- | --------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`          | `string`  | 必須 | 使用するモデルID。"AGENTIC STAR" を指定してください。                                                                                                                                                      |
| `messages`       | `array`   | 必須 | メッセージオブジェクトの配列。少なくとも 1 つの user ロールメッセージが必要。複数の user メッセージを含めても最後の 1 件のみが処理されます。会話履歴はサーバー側で管理されるため、過去のやり取りを messages 配列で送る必要はありません。既存の会話を継続する場合は conversationId パラメータに前回の会話 ID を指定してください。 |
| `stream`         | `boolean` | 必須 | true を指定してください。現在、ストリーミングモードのみサポートしています。                                                                                                                                                 |
| `conversationId` | `string`  | —  | 既存の会話を継続する場合に会話IDを指定します。省略すると新しい会話が作成されます。                                                                                                                                               |

#### エディション固有のパラメータ

Marketplace

|                |          |                                                                                                                             |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `agentId`      | `string` | 使用するエージェントのID（必須）。`GET /v1/marketplace-agents` が返す marketplaceAgentId を指定します。                                               |
| `outputFormat` | `string` | 応答テキストの形式。"plain"（省略時）は Markdown 記法を除去したプレーンテキスト（図は削除され、コードブロックは本文が残り、リンクは「文字 (URL)」になる）。"markdown" は Markdown 記法をそのまま保持する。 |

#### Message オブジェクト

| パラメータ     | 型                 | 必須 | 説明                                                                                      |
| --------- | ----------------- | -- | --------------------------------------------------------------------------------------- |
| `role`    | `string`          | 必須 | "user" を指定。"assistant" / "system" は受理されますが、現状のエージェント実行では "user" のみが対話の起点として使用されます       |
| `content` | `string \| array` | 必須 | メッセージの内容。文字列、または content parts (text / input\_file) の配列。処理対象となるテキストは UTF-8 換算で 1 MB 以下。 |

#### コンテンツパーツ（配列形式の場合）

content を配列で指定する場合、以下のパーツタイプが利用できます。テキストとファイルを組み合わせて送信できます。

| type           | パラメータ             | 説明                                      |
| -------------- | ----------------- | --------------------------------------- |
| `"text"`       | `text (string)`   | テキストメッセージ                               |
| `"input_file"` | `fileId (string)` | アップロード済みファイルの `fileId`。1リクエストあたり合計最大20件 |

#### リクエスト例

**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": "売上データを分析してください"
    }
  ]
}'
```

**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": "売上データを分析してください"}],
  },
  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: "売上データを分析してください" }],
  }),
}
);

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>" // Step 1 で取得したアクセストークン

  body, _ := json.Marshal(map[string]interface{}{
      "model":  "AGENTIC STAR",
      "agentId": "<your-agent-id>",
      "stream": true,
      "messages": []map[string]string{
          {"role": "user", "content": "売上データを分析してください"},
      },
  })

  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)
              }
          }
      }
  }
}
```

#### レスポンスヘッダー

| ヘッダー                | 説明                              |
| ------------------- | ------------------------------- |
| `Content-Type`      | text/event-stream               |
| `X-Conversation-Id` | 会話ID。新規会話の場合はサーバーが生成したIDが返されます。 |
| `X-Message-Id`      | アシスタントの応答メッセージID。               |

#### SSE レスポンス形式

レスポンスは以下の順序でSSEイベントとして配信されます。各イベントは data: プレフィックス付きのJSON行です。

SSEイベントフロー

1

<!-- -->

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

2

<!-- -->

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

3

<!-- -->

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

4

<!-- -->

. `data: [DONE]`

レスポンスは SSE（Server-Sent Events）ストリーミングで配信されます。各チャンクは OpenAI 互換の ChatCompletionChunk 形式です。接続ライフサイクル、レスポンスオブジェクトの詳細、エージェント拡張フィールド、エラーハンドリングについては[ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md)を参照してください。

#### レスポンス例

```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":"売上データ"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"を分析します。"},"finishReason":null}]}

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

data: [DONE]
```

#### エラーレスポンス

SSEストリーム開始前のエラーはJSON形式で返されます。ストリーム中のエラーはSSEチャンクとして配信されます。

| ステータス | 説明                                                                                                                                                                                                                           |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | リクエストパラメータ不正（model / messages / stream / conversationId / role / content の欠落・型不一致、または input\_file が1リクエストあたり20件を超過）。ボディが壊れた JSON（`code: "invalid_body"`）。または、指定した `conversationId` がアーカイブ済み（`code: "conversation_archived"`） |
| `400` | messages に user ロールのメッセージが 1 つも無い（`code: "no_user_message"`）                                                                                                                                                                 |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                                                  |
| `403` | 指定した会話がプロジェクトの会話（`code: "project_conversation"`。プロジェクトの会話には送れません）                                                                                                                                                            |
| `404` | 指定した input\_file の `fileId` が見つからない（`code: "file_not_found"`）                                                                                                                                                                |
| `409` | 指定した会話が現在処理中（`code: "conversation_processing"`）                                                                                                                                                                              |

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

進行中の会話のSSEストリームに再接続します。エージェントが長時間実行タスクを処理している場合や、ネットワーク切断後の復帰に使用します。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明         |
| ---------------- | -------- | -- | ---------- |
| `conversationId` | `string` | 必須 | 再接続する会話のID |

#### リクエスト例

**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())
}
```

#### レスポンス（200 OK）

SSE ストリームに再接続します。レスポンス形式は [POST /v1/chat/completions](#chat) と同じです。レスポンスヘッダーに `X-Conversation-Id` と `X-Message-Id` が含まれます。再接続の詳細な手順については[ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md)を参照してください。

#### エラーレスポンス

| ステータス | code        | 説明                                                       |
| ----- | ----------- | -------------------------------------------------------- |
| `404` | `not_found` | 会話が見つからない、進行中でない、または自分の会話ではない（conversationId が空の値のときも同じ） |

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

進行中の会話をキャンセルします。エージェントの実行を中断する場合に使用します。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明           |
| ---------------- | -------- | -- | ------------ |
| `conversationId` | `string` | 必須 | キャンセルする会話のID |

#### リクエストボディ（任意）

| パラメータ       | 型        | 必須 | 説明                                    |
| ----------- | -------- | -- | ------------------------------------- |
| `messageId` | `string` | —  | キャンセル対象のメッセージID（UUID）。省略時は会話全体のキャンセル。 |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド            | 型         | 説明                  |
| ---------------- | --------- | ------------------- |
| `conversationId` | `string`  | キャンセルされた会話のID（UUID） |
| `cancelled`      | `boolean` | キャンセル成功時は常に true    |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | 説明                                                                                                                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | conversationId が不正、messageId が文字列ではない、ボディが壊れた JSON または JSON のオブジェクトではない（`code: "invalid_body"`）、または会話がアーカイブ済み（`code: "conversation_archived"`）                                                          |
| `400` | messageId のメッセージが、指定した会話のものではない（`code: "conversation_mismatch"`）                                                                                                                                        |
| `400` | この会話の接続先がキャンセルに対応していない（`code: "unsupported_endpoint"`）、またはこの環境でキャンセルが有効になっていない（`code: "post_processing_not_enabled"`）                                                                                   |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                             |
| `404` | 会話が見つからない、またはメッセージを止められない（`code: "message_not_found"`）。`message_not_found` は、送った直後で 10 秒ほど待っても止められなかったとき（数秒後にもう一度送れば止まります）と、messageId のメッセージが無い、または自分のものではないとき（送り直しても止まりません。messageId を確かめてください）の 2 つです |
| `404` | messageId のメッセージが処理中ではない（すでに終わっている。`code: "not_processing"`）                                                                                                                                            |

## 登録 Agent の一覧

チャットで動かせる登録 Agent の一覧を取得します。

### エンドポイント一覧

| メソッド | エンドポイント                  | 説明              |
| ---- | ------------------------ | --------------- |
| GET  | `/v1/marketplace-agents` | 登録 Agent の一覧を取得 |

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

チャット（`POST /v1/chat/completions` の `agentId`）で動かせる登録 Agent を、全部返します（有効なものだけ）。MCP の受け口が有効な配備でチャットの組（`?toolsets=chat`。指定が無いときの既定）を使うときは MCP（`execute_chat` の `agentId`）、A2A の受け口が有効な配備では A2A（`/v1/a2a/agents/{agentId}/`）でも、同じ Agent を動かせます。MCP の `list_agents` と同じ一覧です。一覧は最大 5 分前のものです。`marketplaceAgentId` を、チャットでは `agentId` に指定します。

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                                    | 型          | 説明                                  |
| ---------------------------------------- | ---------- | ----------------------------------- |
| `marketplaceAgents`                      | `array`    | 登録 Agent の配列（有効なものの全部）              |
| `marketplaceAgents[].marketplaceAgentId` | `string`   | 登録 Agent の ID。チャットでは agentId に指定します |
| `marketplaceAgents[].displayName`        | `string`   | 表示名                                 |
| `marketplaceAgents[].description`        | `string`   | 説明。説明が無い Agent は表示名                 |
| `marketplaceAgents[].tags`               | `string[]` | タグ                                  |
| `hasMore`                                | `boolean`  | いつも false（全部を返します）                  |

#### レスポンス例

```json
{
  "marketplaceAgents": [
    {
      "marketplaceAgentId": "sales-report",
      "displayName": "売上レポート",
      "description": "売上データを集計して報告書を作ります",
      "tags": ["report"]
    }
  ],
  "hasMore": false
}
```

#### エラーレスポンス

| ステータス | code                        | 説明                   |
| ----- | --------------------------- | -------------------- |
| `401` | `—`                         | トークンが無い・無効（共通のエラーの節） |
| `502` | `upstream_connection_error` | 登録 Agent の一覧を読めなかった  |
| `502` | `upstream_api_error`        | 一覧の読み取り先が誤りを返した      |
| `504` | `upstream_timeout`          | 一覧の読み取りが時間内に終わらなかった  |

## 会話管理

会話の一覧取得・メッセージ履歴参照・削除・タイトル更新を行います。

### エンドポイント一覧

| メソッド   | エンドポイント                                      | 説明           | スコープ (SaaS)    |
| ------ | -------------------------------------------- | ------------ | -------------- |
| GET    | `/v1/conversations`                          | 会話一覧を取得      | `chat:history` |
| GET    | `/v1/conversations/:conversationId/messages` | メッセージ履歴を取得   | `chat:history` |
| PATCH  | `/v1/conversations/:conversationId`          | 会話のタイトルを更新   | `chat:history` |
| DELETE | `/v1/conversations/:conversationId`          | 会話を削除        | `chat:history` |
| POST   | `/v1/conversations/:conversationId/restore`  | アーカイブ済み会話を復元 | `chat:history` |
| POST   | `/v1/conversations/:conversationId/read`     | 会話を既読にする     | `chat:history` |

※ Marketplace 版はスコープ不要（認証のみ）。

**アーカイブ済みの会話は、管理者が保持の期間を決めていると、アーカイブしてからその日数を過ぎたときに自動で削除されます。** メッセージと、その会話だけで使っていた添付・成果物のファイルも一緒に削除されます。保持の期間を決めていなければ、削除されません。

#### アーカイブ会話への操作制約

`mode=archive` で取得できるアーカイブ済み会話は、参照系の操作（一覧取得・メッセージ履歴取得）と復元のみ可能です。以下の操作は 400 エラー（`code: "conversation_archived"`）になります。

| 操作                                     | アーカイブ済みでの動作                                                        |
| -------------------------------------- | ------------------------------------------------------------------ |
| `GET /v1/conversations?mode=archive`   | ✅ 取得可能                                                             |
| `GET /v1/conversations/:id/messages`   | ✅ 取得可能（`messages[].archived: true` 付与）                             |
| `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`（既存会話継続）    | ❌ 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`   | ✅ active に戻す                                                       |

### GET`/v1/conversations`

会話一覧を取得します。カーソルベースのページネーションに対応しています。

#### クエリパラメータ

| パラメータ    | 型         | 必須 | デフォルト      | 説明                                                                                      |
| -------- | --------- | -- | ---------- | --------------------------------------------------------------------------------------- |
| `limit`  | `integer` | —  | `50`       | 取得件数（1〜100）                                                                             |
| `cursor` | `string`  | —  | —          | 次ページ取得用カーソル（前回レスポンスの cursor 値）                                                          |
| `order`  | `string`  | —  | `"desc"`   | "asc" または "desc"                                                                        |
| `title`  | `string`  | —  | —          | タイトルで絞り込み                                                                               |
| `mode`   | `string`  | —  | `"active"` | "active"（通常会話）または "archive"（アーカイブ済み会話）。\`mode\` を切り替えると別データストアになるため、\`cursor\` は引き継げません |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                            | 型          | 説明                                                                                                                              |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `conversations`                  | `array`    | 会話オブジェクトの配列                                                                                                                     |
| `conversations[].conversationId` | `string`   | 会話の一意識別子（UUID）                                                                                                                  |
| `conversations[].title`          | `string`   | 会話のタイトル                                                                                                                         |
| `conversations[].type`           | `string?`  | 会話の種類。"chat"（チャット）・"mail"（メールから始めた会話）。プロジェクトの工程の会話は一覧に含まれません（会話 ID を指定すればメッセージを取得できます）。`mode=archive` では返しません                   |
| `conversations[].createdAt`      | `string`   | 作成日時（ISO 8601）                                                                                                                  |
| `conversations[].updatedAt`      | `string`   | 最終更新日時（ISO 8601）                                                                                                                |
| `conversations[].archived`       | `boolean?` | アーカイブ済みかどうか。`mode=archive` で取得した場合は常に `true`。`mode=active` でこのフィールドが `true` で返るのは、archive 状態のまま active 一覧から取得された場合のみで、通常は省略されます |
| `hasMore`                        | `boolean`  | 次のページが存在するかどうか                                                                                                                  |
| `cursor`                         | `string`   | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                                                           |

#### レスポンス例

```json
{
  "conversations": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "売上データ分析",
      "type": "chat",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}
```

#### エラーレスポンス

| ステータス | code                        | 説明                                                                                                                                         |
| ----- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400` | `invalid_parameter`         | limit パラメータが不正（1〜100の範囲外）、mode が "active" / "archive" 以外、order が "asc" / "desc" 以外、cursor が不正（前回レスポンスの値以外）、または title が文字列ではない（複数回指定した場合など） |
| `502` | `upstream_connection_error` | 会話の一覧を取得できなかった（時間をおいて再試行してください）                                                                                                            |

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

指定した会話のメッセージ履歴を取得します。カーソルベースのページネーションに対応しています。取得しても会話は既読になりません（MCP・A2A で読んでも同じです）。既読にするには[会話を既読にする](#read-conversation)を呼びます。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明          |
| ---------------- | -------- | -- | ----------- |
| `conversationId` | `string` | 必須 | 会話のID（UUID） |

#### クエリパラメータ

| パラメータ    | 型         | 必須 | デフォルト    | 説明                             |
| -------- | --------- | -- | -------- | ------------------------------ |
| `limit`  | `integer` | —  | `50`     | 1 ページの取得件数（1-100）              |
| `cursor` | `string`  | —  | —        | 次ページ取得用カーソル（前回レスポンスの cursor 値） |
| `order`  | `string`  | —  | `"desc"` | "asc" または "desc"               |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                                 | 型          | 説明                                                                                                |
| ------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `messages`                            | `array`    | メッセージオブジェクトの配列                                                                                    |
| `messages[].conversationId`           | `string`   | 会話ID（UUID）                                                                                        |
| `messages[].messageId`                | `string`   | メッセージの一意識別子                                                                                       |
| `messages[].sender`                   | `string`   | 送信者。"User" または "AI"                                                                               |
| `messages[].text`                     | `string`   | メッセージの本文テキスト。本文が空のときは、いちばん新しいタスクの結果（`content`）が入ります                                               |
| `messages[].createdAt`                | `string`   | 作成日時（ISO 8601）                                                                                    |
| `messages[].updatedAt`                | `string`   | 最終更新日時（ISO 8601）                                                                                  |
| `messages[].status`                   | `object`   | メッセージの処理状態                                                                                        |
| `messages[].status.processing`        | `boolean`  | エージェントが現在処理中かどうか                                                                                  |
| `messages[].status.unfinished`        | `boolean`  | エージェントの応答が中断されたかどうか                                                                               |
| `messages[].tasks`                    | `array`    | エージェントが実行したタスクの配列（後述）                                                                             |
| `messages[].deliverables`             | `array`    | エージェントが生成した成果物の配列。存在する場合のみ含まれます                                                                   |
| `messages[].deliverables[].filename`  | `string`   | 成果物のファイル名                                                                                         |
| `messages[].deliverables[].filepath`  | `string`   | 成果物のファイルパス                                                                                        |
| `messages[].deliverables[].source`    | `string`   | `"agent"`（エージェント生成）または `"user"`（ユーザーアップロード）                                                       |
| `messages[].deliverables[].isPrimary` | `boolean`  | 主要成果物かどうか                                                                                         |
| `messages[].deliverables[].createdAt` | `string`   | 作成日時（ISO 8601形式）。分からないときは空文字                                                                      |
| `messages[].deliverables[].mimeType`  | `string`   | MIME タイプ（例: `"application/pdf"`、`"text/markdown"`）。判定できない場合は `"application/octet-stream"`         |
| `messages[].deliverables[].size`      | `number?`  | ファイルサイズ（バイト）。0 以下の場合は省略                                                                           |
| `messages[].files`                    | `array?`   | ユーザーが添付したファイルの配列。`sender: "User"` のメッセージで添付がある場合のみ含まれます                                           |
| `messages[].files[].fileId`           | `string`   | ファイルの一意識別子（UUID）                                                                                  |
| `messages[].files[].mimeType`         | `string`   | MIME タイプ（例: `"image/png"`、`"application/pdf"`）                                                    |
| `messages[].files[].width`            | `number?`  | 画像の幅（ピクセル）。画像ファイルの場合のみ                                                                            |
| `messages[].files[].height`           | `number?`  | 画像の高さ（ピクセル）。画像ファイルの場合のみ                                                                           |
| `messages[].archived`                 | `boolean?` | archive 経由で取得されたメッセージのみ `true`。`GET /v1/conversations?mode=archive` で取得した会話のメッセージ履歴を参照した場合に付与されます |
| `hasMore`                             | `boolean`  | 次のページが存在するかどうか                                                                                    |
| `cursor`                              | `string`   | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                             |

#### Task オブジェクト

| フィールド            | 型         | 説明                                                                                                                                                                           |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId`      | `string`  | タスクが属するメッセージのID                                                                                                                                                              |
| `conversationId` | `string`  | タスクが属する会話のID                                                                                                                                                                 |
| `callId`         | `string?` | ツール呼び出しID。Complex Path では複数のタスクが同じ callId を共有し、同一ツール呼び出しのステップ列を識別するために利用される                                                                                                  |
| `actionType`     | `string`  | タスクの種類（例: ツール実行、コード生成）                                                                                                                                                       |
| `title`          | `string?` | タスクのタイトル。存在しない場合は省略される                                                                                                                                                       |
| `description`    | `string?` | タスクの説明。存在しない場合は省略される                                                                                                                                                         |
| `status`         | `string`  | タスクの状態。値は "in\_progress" / "completed" / "failed" / "error" / "pending" のいずれか                                                                                                |
| `content`        | `string?` | タスクの実行結果テキスト。存在しない場合は省略される                                                                                                                                                   |
| `metadata`       | `object?` | actionType ごとに異なる補助情報（sub\_event\_type、url、filepath など）。詳細は [ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md) を参照 |
| `files`          | `array?`  | タスクに関連するファイル（`filename` / `size` / `filepath` / `mimeType?` の構造。MIME タイプ判定不能時は `mimeType` を省略）。タスクに関連ファイルがない場合は配列自体が省略される                                                    |
| `timestamp`      | `number`  | タスク実行時のタイムスタンプ（Unix ミリ秒）                                                                                                                                                     |
| `createdAt`      | `string`  | 作成日時（ISO 8601）                                                                                                                                                               |
| `updatedAt`      | `string`  | 更新日時（ISO 8601）                                                                                                                                                               |

<!-- -->

#### ページネーション

`limit` を指定すると、その件数ずつ取得できます。`hasMore` が `true` の間、レスポンスの `cursor` をそのまま次のリクエストに渡してください。

**リクエスト例**

**curl**

```bash
# 1ページ目
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
-H "Authorization: Bearer <access_token>"

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

`limit` を省略した場合は 50 件が返ります。全件を取得する場合は、`hasMore` が `false` になるまで `cursor` で続きを取得してください。

> **カーソル利用時の注意**
>
> `cursor` は取得位置を表すため、同じカーソルを使い続ける間は `order` を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。
>
> また、ページを取得している間にメッセージが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

> **未知のフィールドは安全に無視**
>
> 実装は将来 `actionType` / `metadata` に新規フィールドを追加する可能性があります。クライアント実装では、本表に記載されていないフィールドは安全に無視するようにしてください。詳細な metadata 構造は [ストリーミングガイド — Task データモデル](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md#task-data-model) を参照してください。

#### レスポンス例

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "sender": "User",
      "text": "売上データを分析してください",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:30:00Z",
      "status": { "processing": false, "unfinished": false },
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### エラーレスポンス

| ステータス | code                      | 説明                                                                            |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000）。この値は受け付けません |
| `400` | `invalid_parameter`       | limit が 1-100 の整数でない、cursor が不正（前回レスポンスの値以外）、または order が "asc" / "desc" 以外    |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |

<!-- -->

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

会話のタイトルを更新します。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明          |
| ---------------- | -------- | -- | ----------- |
| `conversationId` | `string` | 必須 | 会話のID（UUID） |

#### リクエストボディ

| パラメータ   | 型        | 必須 | 説明                 |
| ------- | -------- | -- | ------------------ |
| `title` | `string` | 必須 | 新しい会話タイトル（200文字以内） |

#### リクエスト例

**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": "新しいタイトル" }'
```

**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": "新しいタイトル"},
)

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: "新しいタイトル" }),
}
);

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

**Go**

```go
payload := map[string]string{"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()
```

#### レスポンスフィールド（200 OK）

| フィールド            | 型        | 説明                                          |
| ---------------- | -------- | ------------------------------------------- |
| `conversationId` | `string` | 会話ID（UUID）                                  |
| `title`          | `string` | 更新後のタイトル                                    |
| `type`           | `string` | 会話の種類。"chat"・"mail"・"project"（プロジェクトの工程の会話） |
| `createdAt`      | `string` | 会話の作成日時（ISO 8601）                           |
| `updatedAt`      | `string` | 会話の更新日時（ISO 8601）                           |

#### レスポンス例

```json
{
  "conversationId": "550e8400-...",
  "title": "新しいタイトル",
  "type": "chat",
  "createdAt": "2026-03-14T10:30:00.000Z",
  "updatedAt": "2026-03-14T12:00:00.000Z"
}
```

#### エラーレスポンス

| ステータス | code                      | 説明                                                                            |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000）。この値は受け付けません |
| `400` | `missing_parameter`       | title が未指定                                                                    |
| `400` | `invalid_title`           | title が空文字・文字列ではない・200 文字を超える                                                 |
| `400` | `invalid_body`            | ボディが壊れた JSON                                                                  |
| `400` | `conversation_archived`   | 会話がアーカイブ済み                                                                    |
| `415` | `unsupported_media_type`  | ボディの Content-Type が application/json ではない                                     |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |

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

会話を削除します。その会話のメッセージに添付したファイルと成果物のファイルのうち、ほかの会話で使っていないものも削除されます（`GET /v1/files` にも出なくなります）。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明          |
| ---------------- | -------- | -- | ----------- |
| `conversationId` | `string` | 必須 | 会話のID（UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド            | 型         | 説明               |
| ---------------- | --------- | ---------------- |
| `conversationId` | `string`  | 削除された会話のID（UUID） |
| `deleted`        | `boolean` | 削除成功時は常に true    |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                      | 説明                                                                            |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000）。この値は受け付けません |
| `400` | `conversation_archived`   | 会話がアーカイブ済み。復元には `POST /v1/conversations/:id/restore` を使用                      |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |
| `409` | `conversation_processing` | 会話が現在処理中のため削除できない                                                             |
| `409` | `project_conversation`    | プロジェクトの会話。プロジェクトの会話は削除できません                                                   |
| `409` | `legal_hold`              | 保全中の会話。管理者が保全を解除するまで削除できません                                                   |

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

アーカイブ済み会話を active に戻します。復元後は通常会話と同様に編集・継続・削除が可能になります。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明                 |
| ---------------- | -------- | -- | ------------------ |
| `conversationId` | `string` | 必須 | アーカイブ済み会話のID（UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド            | 型         | 説明               |
| ---------------- | --------- | ---------------- |
| `conversationId` | `string`  | 復元された会話のID（UUID） |
| `restored`       | `boolean` | 復元成功時は常に true    |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                      | 説明                                                                            |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000）。この値は受け付けません |
| `404` | `conversation_not_found`  | アーカイブに該当会話が存在しない、または既に active（archive 状態と区別されません）                             |

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

会話を既読にします。会話のメッセージを API（REST・MCP・A2A）で読んでも既読にはならないので、読んだことを残すときに呼びます。既読の位置は後ろに戻りません（前のメッセージを指定しても、今より前には戻りません）。

<!-- -->

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明          |
| ---------------- | -------- | -- | ----------- |
| `conversationId` | `string` | 必須 | 会話のID（UUID） |

#### リクエストボディ（任意）

本文は省けます。付けるときは `Content-Type: application/json` で送ります。

| パラメータ       | 型        | 必須 | 説明                                                                       |
| ----------- | -------- | -- | ------------------------------------------------------------------------ |
| `messageId` | `string` | —  | 読んだ最後のメッセージのID。省くと、その時点の最新のメッセージまで既読にします（読んでいる間に届いたメッセージを既読にしないときに指定します） |

#### リクエスト例

**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"}'
```

#### レスポンス（204 No Content）

本文はありません。

#### エラーレスポンス

| ステータス | code                      | 説明                                                                            |
| ----- | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000）。この値は受け付けません |
| `400` | `invalid_parameter`       | messageId が空・文字列ではない                                                          |
| `400` | `invalid_body`            | 本文が JSON のオブジェクトではない                                                          |
| `400` | `conversation_archived`   | 会話がアーカイブ済み                                                                    |
| `415` | `unsupported_media_type`  | 本文が application/json でない                                                      |
| `404` | `conversation_not_found`  | 会話が存在しない・自分の会話でない                                                             |
| `404` | `message_not_found`       | messageId がその会話に無い                                                            |

## ファイル管理

ファイルのアップロード・取得・削除を行います。

### エンドポイント一覧

| メソッド   | エンドポイント                     | 説明          | スコープ (SaaS) |
| ------ | --------------------------- | ----------- | ----------- |
| GET    | `/v1/files`                 | ファイル一覧を取得   | `chat:file` |
| POST   | `/v1/files`                 | ファイルをアップロード | `chat:file` |
| GET    | `/v1/files/:fileId/content` | ファイルをダウンロード | `chat:file` |
| DELETE | `/v1/files/:fileId`         | ファイルを削除     | `chat:file` |

※ Marketplace 版はスコープ不要（認証のみ）。

### POST`/v1/files`

ファイルをアップロードします。

#### リクエストボディ（multipart/form-data）

| パラメータ      | 型        | 必須 | 説明                         |
| ---------- | -------- | -- | -------------------------- |
| `file`     | `file`   | 必須 | アップロードするファイル。サイズ上限 512 MB。 |
| `filename` | `string` | 必須 | ファイル名                      |

#### リクエスト例

**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())
```

#### レスポンスフィールド（201 Created）

| フィールド       | 型         | 説明                      |
| ----------- | --------- | ----------------------- |
| `fileId`    | `string`  | ファイルの一意識別子（UUID）        |
| `filename`  | `string`  | ファイル名                   |
| `bytes`     | `integer` | ファイルサイズ（バイト）            |
| `createdAt` | `string`  | 作成日時（ISO 8601）          |
| `width`     | `integer` | 画像の幅（ピクセル）。画像ファイルの場合のみ  |
| `height`    | `integer` | 画像の高さ（ピクセル）。画像ファイルの場合のみ |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                              | 説明                                                                              |
| ----- | --------------------------------- | ------------------------------------------------------------------------------- |
| `400` | `missing_parameter`               | file または filename パラメータが未指定                                                     |
| `400` | `file_too_large`                  | ファイルサイズが 512 MB を超過                                                             |
| `400` | `invalid_parameter`               | アップロードされた画像ファイルが破損している/不正                                                       |
| `415` | `unsupported_media_type`          | ボディが multipart/form-data ではない、またはファイルの種類を受け付けていない（環境で受け付けないと決めた拡張子・MIME タイプを含む） |
| `403` | `feature_not_permitted`           | 管理者がファイルの添付を許可していない                                                             |
| `503` | `feature_permissions_unavailable` | 機能の許可を確かめられない。時間をおいて送り直す                                                        |

### GET`/v1/files`

ファイル一覧を取得します。カーソルベースのページネーションに対応しています。

#### クエリパラメータ

| パラメータ    | 型         | 必須 | デフォルト    | 説明                                         |
| -------- | --------- | -- | -------- | ------------------------------------------ |
| `limit`  | `integer` | —  | `50`     | 1 ページの取得件数（1-100）                          |
| `cursor` | `string`  | —  | —        | 次ページ取得用カーソル（前回レスポンスの cursor 値）             |
| `order`  | `string`  | —  | `"desc"` | "asc"（古い順）または "desc"（新しい順）。並びの基準はファイルの更新日時 |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド               | 型         | 説明                                    |
| ------------------- | --------- | ------------------------------------- |
| `files`             | `array`   | ファイルオブジェクトの配列                         |
| `files[].fileId`    | `string`  | ファイルの一意識別子（UUID）                      |
| `files[].filename`  | `string`  | ファイル名                                 |
| `files[].bytes`     | `integer` | ファイルサイズ（バイト）                          |
| `files[].createdAt` | `string`  | 作成日時（ISO 8601）                        |
| `files[].width`     | `integer` | 画像の幅（ピクセル）。画像ファイルの場合のみ                |
| `files[].height`    | `integer` | 画像の高さ（ピクセル）。画像ファイルの場合のみ               |
| `hasMore`           | `boolean` | 次のページが存在するかどうか                        |
| `cursor`            | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |

#### レスポンス例

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

#### ページネーション

`limit` を指定すると、その件数ずつ取得できます。`hasMore` が `true` の間、レスポンスの `cursor` をそのまま次のリクエストに渡してください。

**リクエスト例**

**curl**

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

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://<your-domain>/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

`limit` を省略した場合は 50 件が返ります。全件を取得する場合は、`hasMore` が `false` になるまで `cursor` で続きを取得してください。

> **カーソル利用時の注意**
>
> `cursor` は取得位置を表すため、同じカーソルを使い続ける間は `order` を変更しないでください。条件を変えると対象範囲が変わり、項目の重複や取りこぼしが起きます。
>
> また、ページを取得している間にファイルが追加・削除された場合も、ページ間で重複や取りこぼしが生じることがあります。

#### エラーレスポンス

| ステータス | code                | 説明                        |
| ----- | ------------------- | ------------------------- |
| `400` | `invalid_parameter` | limit が 1-100 の整数でない      |
| `400` | `invalid_parameter` | cursor が不正（前回レスポンスの値以外）   |
| `400` | `invalid_parameter` | order が "asc" / "desc" 以外 |

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

ファイルをダウンロードします。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明           |
| -------- | -------- | -- | ------------ |
| `fileId` | `string` | 必須 | ファイルID（UUID） |

#### リクエスト例

**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)
```

#### レスポンス（200 OK）

ファイルのバイナリデータがストリームで返されます。

| レスポンスヘッダー             | 説明                                                                        |
| --------------------- | ------------------------------------------------------------------------- |
| `Content-Type`        | ファイルの MIME タイプ                                                            |
| `Content-Length`      | ファイルサイズ（バイト）                                                              |
| `Content-Disposition` | attachment; filename="ファイル名"; filename\*=UTF-8''\<UTF-8 をパーセント符号化したファイル名> |

保存するときのファイル名は、`filename*`（UTF-8 をパーセント符号化した名前）があればそちらを使い、無ければ `filename` を使います。日本語などを含む名前では、`filename` は代わりの名前になり、元の名前は `filename*` にだけ入ります。例えば `売上.pdf` のときは次のようになります（`filename` の代わりの名前は一例です）。

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

#### エラーレスポンス

| ステータス | code                  | 説明                                                         |
| ----- | --------------------- | ---------------------------------------------------------- |
| `400` | `invalid_parameter`   | fileId が不正なフォーマット                                          |
| `404` | `file_not_found`      | ファイルが見つからない                                                |
| `503` | `service_unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください |

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

ファイルを削除します。会話を削除したときも、その会話だけで使っていたファイルは削除されます（[会話を削除](#delete-conversation)）。

#### パスパラメータ

| パラメータ    | 型        | 必須 | 説明           |
| -------- | -------- | -- | ------------ |
| `fileId` | `string` | 必須 | ファイルID（UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド     | 型         | 説明                 |
| --------- | --------- | ------------------ |
| `fileId`  | `string`  | 削除されたファイルのID（UUID） |
| `deleted` | `boolean` | 削除成功時は常に true      |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                | 説明                |
| ----- | ------------------- | ----------------- |
| `400` | `invalid_parameter` | fileId が不正なフォーマット |
| `404` | `file_not_found`    | ファイルが見つからない       |

## 成果物取得

エージェントが生成した成果物ファイルを取得します。

### エンドポイント一覧

| メソッド | エンドポイント           | 説明         | スコープ (SaaS) |
| ---- | ----------------- | ---------- | ----------- |
| GET  | `/v1/files/proxy` | 成果物ファイルを取得 | `chat:exec` |

※ Marketplace 版はスコープ不要（認証のみ）。

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

メッセージ履歴の `deliverables[].filepath` で取得したパスを指定して、成果物ファイルをダウンロードします。

<!-- -->

マーケットプレイス版ではスコープによる制限はありません。認証済みのトークンがあれば取得できます。

<!-- -->

<!-- -->

#### クエリパラメータ

| パラメータ  | 型        | 必須 | 説明                                                |
| ------ | -------- | -- | ------------------------------------------------- |
| `path` | `string` | 必須 | 成果物のファイルパス（メッセージ履歴の deliverables\[].filepath で取得） |

#### リクエスト例

`filepath` は [メッセージ履歴の取得](#get-messages) の `messages[].deliverables[].filepath` の値です。

**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)
```

#### レスポンス（200 OK）

成果物ファイルのバイナリデータがストリームで返されます。

| レスポンスヘッダー        | 説明             |
| ---------------- | -------------- |
| `Content-Type`   | ファイルの MIME タイプ |
| `Content-Length` | ファイルサイズ（バイト）   |

#### エラーレスポンス

| ステータス | code                  | 説明                                                         |
| ----- | --------------------- | ---------------------------------------------------------- |
| `400` | `missing_parameter`   | path パラメータが未指定                                             |
| `400` | `invalid_parameter`   | path のフォーマットが不正（UUID の形の段が無い）                              |
| `404` | `not_found`           | ファイルが見つからない（保存先の応答に別の code があるときはその code）                  |
| `500` | `unknown`             | 保存先の不明な誤り                                                  |
| `500` | `storage_forbidden`   | 保存先へのアクセスが拒否された。管理者に連絡してください                               |
| `500` | `rejected`            | 保存先がリクエストを断った。管理者に連絡してください                                 |
| `503` | `rate_limited`        | 保存先が一時的に混んでいる。時間をおいて再試行してください                              |
| `503` | `transient`           | 保存先が一時的に使えない。時間をおいて再試行してください                               |
| `503` | `service_unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください |

## 検索

メッセージを全文検索します。

### エンドポイント一覧

| メソッド | エンドポイント               | 説明         | スコープ (SaaS)    |
| ---- | --------------------- | ---------- | -------------- |
| GET  | `/v1/search/messages` | メッセージを全文検索 | `chat:history` |

※ Marketplace 版はスコープ不要（認証のみ）。

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

メッセージを全文検索します。プロジェクトの工程の会話のメッセージと、アーカイブ済みの会話のメッセージは、検索の対象になりません。検索結果は作成日時の新しい順（`order=asc` で古い順）に、カーソルベースのページネーションで返します。

#### クエリパラメータ

| パラメータ    | 型         | 必須 | 説明                                                                         |
| -------- | --------- | -- | -------------------------------------------------------------------------- |
| `q`      | `string`  | 必須 | 検索クエリ                                                                      |
| `order`  | `string`  | —  | ソート順。"asc"（昇順）または "desc"（降順、デフォルト）                                         |
| `limit`  | `integer` | —  | 1 ページの件数（1〜100）。デフォルトは 50 件です                                              |
| `cursor` | `string`  | —  | 次のページを取得するためのカーソル値。前回のレスポンスに含まれる cursor をそのまま指定します。q と order は前回と同じにしてください |

#### リクエスト例

**Search messages**

**curl**

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

**Python**

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

query = "売上"
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 = "売上";
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 := "売上"
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)
```

#### レスポンスフィールド（200 OK）

| フィールド                                 | 型         | 説明                                                                                                                                                                                   |
| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `messages`                            | `array`   | 検索結果のメッセージ配列（1 ページ分。limit 件まで）                                                                                                                                                       |
| `messages[].conversationId`           | `string`  | 会話ID（UUID）                                                                                                                                                                           |
| `messages[].messageId`                | `string`  | メッセージの一意識別子                                                                                                                                                                          |
| `messages[].text`                     | `string`  | メッセージの本文テキスト                                                                                                                                                                         |
| `messages[].title`                    | `string`  | 会話のタイトル                                                                                                                                                                              |
| `messages[].sender`                   | `string`  | 送信者。"User" または "AI"                                                                                                                                                                  |
| `messages[].createdAt`                | `string`  | 作成日時（ISO 8601）                                                                                                                                                                       |
| `messages[].updatedAt`                | `string`  | 最終更新日時（ISO 8601）                                                                                                                                                                     |
| `messages[].matchedQueries`           | `array`   | 一致した検索クエリの配列                                                                                                                                                                         |
| `messages[].status`                   | `object`  | メッセージの処理状態                                                                                                                                                                           |
| `messages[].status.processing`        | `boolean` | エージェントが現在処理中かどうか                                                                                                                                                                     |
| `messages[].status.unfinished`        | `boolean` | エージェントの応答が中断されたかどうか                                                                                                                                                                  |
| `messages[].tasks`                    | `array`   | エージェントが実行したタスクの配列。フィールド定義は [GET /v1/conversations/:conversationId/messages](#get-messages) の Task オブジェクトを参照                                                                          |
| `messages[].deliverables`             | `array`   | エージェントが生成した成果物の配列。存在する場合のみ含まれます                                                                                                                                                      |
| `messages[].deliverables[].filename`  | `string`  | 成果物のファイル名                                                                                                                                                                            |
| `messages[].deliverables[].filepath`  | `string`  | 成果物のファイルパス                                                                                                                                                                           |
| `messages[].deliverables[].source`    | `string`  | `"agent"`（エージェント生成）または `"user"`（ユーザーアップロード）                                                                                                                                          |
| `messages[].deliverables[].isPrimary` | `boolean` | 主要成果物かどうか                                                                                                                                                                            |
| `messages[].deliverables[].createdAt` | `string`  | 作成日時（ISO 8601形式）。分からないときは空文字                                                                                                                                                         |
| `messages[].deliverables[].mimeType`  | `string`  | MIME タイプ（例: `"application/pdf"`、`"text/markdown"`）。判定できない場合は `"application/octet-stream"`                                                                                            |
| `messages[].deliverables[].size`      | `number?` | ファイルサイズ（バイト）。0 以下の場合は省略                                                                                                                                                              |
| `messages[].files`                    | `array?`  | ユーザーが添付したファイルの配列。`sender: "User"` のメッセージで添付がある場合のみ含まれます。フィールド構造は履歴 API と同じ（`fileId` / `mimeType` / `width?` / `height?`）。詳細は [GET /v1/conversations/:id/messages](#get-messages) を参照 |
| `hasMore`                             | `boolean` | 続きのページがあれば true。true のときは cursor が返ります                                                                                                                                               |
| `cursor`                              | `string`  | 次のページを取得するためのカーソル値。hasMore が true のときだけ含まれます                                                                                                                                         |
| `limitReached`                        | `boolean` | 一致したメッセージが多く、一致の度合いの高い上位の結果（本文の一致と、エージェントの作業の経過の一致のそれぞれ 1,000 件まで）だけを対象にしているときだけ true。そうでないときは含まれません。もれなく探すときは検索クエリを絞ってください                                                          |

#### レスポンス例

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "text": "売上データを分析した結果...",
      "title": "売上データ分析",
      "sender": "AI",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z",
      "matchedQueries": ["売上"],
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### エラーレスポンス

| ステータス | 説明                                                                                                                  |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `400` | q パラメータが未指定、または 1 つの文字列として指定されていない（q を複数回指定した場合など）。order が "asc" / "desc" 以外、limit が 1〜100 の整数ではない、または cursor が読めない |
| `501` | 検索の設定が無い環境（`code: "search_not_configured"`）                                                                         |
| `503` | 検索が一時的に使えない（`code: "service_unavailable"`）。時間をおいて送り直してください                                                          |

## プロジェクト

プロジェクトは、複数のエージェントを配置して業務を進める単位です。外部システムから、プロジェクトの一覧取得・実行の開始・実行状況の確認<!-- -->・ワークフローの実行の成果物の取得<!-- -->ができます。

プロジェクトには 2 つの型があり、実行の起こし方が異なります。

| 型          | 説明                                                      | 実行の起こし方                                                   |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------- |
| `workflow` | 工程を順に進める型。最初の有効な工程から実行を開始します。                           | `POST /v1/projects/{projectId}/runs`                      |
| `cycle`    | 複数のエージェントをそれぞれのスケジュールで動かし続ける型。外部イベントによる臨時の 1 回を上乗せできます。 | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire` |

> **操作できる範囲**
>
> サービスアカウントのトークンで操作できるのは、この環境にあるすべてのプロジェクトです。アプリケーション（外部ツールでのログイン）のトークンでも、ここにある 9 つのエンドポイントと、ほかのプロジェクトの API を呼べます。そのときに操作できる範囲は、プロジェクトへの参加状況と組織の運用の役割で決まります（[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md)）。外部ツールでのログイン以外で得た利用者のトークンで呼ぶと、どのエンドポイントも `404 Not Found` が返ります。

### エンドポイント一覧

| メソッド | エンドポイント                                                    | 説明                  |
| ---- | ---------------------------------------------------------- | ------------------- |
| GET  | `/v1/projects`                                             | プロジェクト一覧を取得         |
| POST | `/v1/projects/{projectId}/runs`                            | プロジェクトの実行を開始        |
| POST | `/v1/projects/{projectId}/triggers/{triggerId}/fire`       | トリガーを発火して臨時に 1 回実行  |
| GET  | `/v1/projects/{projectId}/runs/{runId}`                    | 実行状況を取得             |
| POST | `/v1/projects/{projectId}/runs/{runId}/cancel`             | ワークフローの実行を中断        |
| POST | `/v1/projects/{projectId}/executions/{executionId}/cancel` | サイクルの巡回の実行を止める      |
| GET  | `/v1/projects/{projectId}/executions/{executionId}`        | 実行の状態を取得（状態の項目だけ）   |
| GET  | `/v1/projects/{projectId}/artifacts`                       | ワークフローの実行の成果物の一覧を取得 |
| GET  | `/v1/projects/{projectId}/artifacts/{artifactId}/content`  | 成果物の中身を取得（HEAD も可）  |

### GET`/v1/projects`

この環境のすべてのプロジェクトの一覧を取得します。<!-- -->カーソルベースのページネーションに対応しています。`cycle` 型のプロジェクトも一覧に含まれますが、実行開始（`POST /v1/projects/{projectId}/runs`）の対象にはなりません。

#### クエリパラメータ

| パラメータ    | 型         | デフォルト | 説明                             |
| -------- | --------- | ----- | ------------------------------ |
| `limit`  | `integer` | `50`  | 取得件数（1〜100）                    |
| `cursor` | `string`  | `—`   | 次ページ取得用カーソル（前回レスポンスの cursor 値） |

上記以外のクエリパラメータは無視されます。

<!-- -->

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                  | 型         | 説明                                                                         |
| ---------------------- | --------- | -------------------------------------------------------------------------- |
| `projects`             | `array`   | プロジェクトオブジェクトの配列                                                            |
| `projects[].projectId` | `string`  | プロジェクト ID（UUID）                                                            |
| `projects[].name`      | `string`  | プロジェクト名                                                                    |
| `projects[].type`      | `string`  | "workflow" または "cycle"                                                     |
| `projects[].status`    | `string`  | プロジェクトの状態。"active" / "paused" / "archived" / "admin\_stopped"（管理者が停止）のいずれか |
| `projects[].tags`      | `array`   | タグの配列。設定されていない場合は空の配列                                                      |
| `hasMore`              | `boolean` | 次のページが存在するかどうか                                                             |
| `cursor`               | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                      |

#### レスポンス例

<!-- -->

<!-- -->

```json
{
  "projects": [
    {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "受注処理フロー",
      "type": "workflow",
      "status": "active",
      "tags": []
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "問い合わせ常時対応",
      "type": "cycle",
      "status": "active",
      "tags": []
    }
  ],
  "hasMore": false
}
```

#### エラーレスポンス

| ステータス | 説明                                                         |
| ----- | ---------------------------------------------------------- |
| `400` | limit（1〜100 の範囲外）または cursor が不正（code は invalid\_parameter） |

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

`workflow` 型のプロジェクトの実行を開始します。`cycle` 型に対して呼び出すと `409 Conflict`（`unsupported_project_type`）が返ります。

#### リクエストヘッダー

| ヘッダー              | 必須 | 説明                                                       |
| ----------------- | -- | -------------------------------------------------------- |
| `Idempotency-Key` | 必須 | 呼び出し側が採番する重複実行の防止キー。8〜128 文字で、使用できる文字は半角英数字と \_ . : - です |

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明               |
| ----------- | -------- | -- | ---------------- |
| `projectId` | `string` | 必須 | プロジェクトの ID（UUID） |

#### リクエストボディ

ボディは省けます。送信する場合は JSON のオブジェクトにしてください。<!-- -->下のフィールドのほかは無視されます。

| パラメータ     | 型        | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                   |
| --------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload` | `any`    | —  | 実行の依頼。JSON の値（オブジェクト・配列・文字列など）を、中身を変えずに受け取ります。最初の工程のエージェントが context.start\_input で受け取ります（マーケットプレイスのワークフローガイドの「外から始めた run の依頼」を参照）。依頼の中にファイルの ID を入れても、ファイルは添付されません。省略・null は依頼なし。JSON の文字列にして 8,000 文字まで                                                                                                                                                             |
| `config`  | `object` | —  | 入力ファイルと工程の設定。{ "placements": \[{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] } の形で、配置と工程の組ごとに書きます。fileBindings は入力ファイルの名前（置ける登録 Agent の一覧の inputs\[].name）から、上げた下書きの artifactId への対応、parameters は登録 Agent の parameters（parametersSchema の形）、connectionBindings は接続の枠の名前から連携先の ID への対応です。placementId・stepId のほかは省けます。省略・null は設定なし |

上限は 2 つあります。`payload` を JSON の文字列にした長さが 8,000 文字を超えると `400 Bad Request`（`payload_too_large`）、ボディ全体が 16 KiB を超えると `413 Payload Too Large`（`body_too_large`）が返ります。

`config` もボディ全体の 16 KiB に含まれます。

#### レスポンスフィールド（201 Created / 200 OK）

| フィールド      | 型          | 説明                                                    |
| ---------- | ---------- | ----------------------------------------------------- |
| `runId`    | `string`   | 実行の ID（UUID）。実行状況の取得に使用します                            |
| `existing` | `boolean?` | 同じ Idempotency-Key での再送により既存の実行を返した場合に true。初回は含まれません |

初回の呼び出しは `201 Created`、同じ `Idempotency-Key` での再送は `200 OK` が返ります。

#### リクエスト例

**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": "ログインできない利用者がいる"
  }
}'
```

**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': 'ログインできない利用者がいる'}},
)

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": "ログインできない利用者がいる"}}),
}
);

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

**Go**

```go
payload := []byte(`{"payload": {"ticketId": "INC-1024", "summary": "ログインできない利用者がいる"}}`)
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)
```

#### レスポンス例

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

> **Idempotency-Key の扱い**
>
> - キーはプロジェクト単位で照合されます。有効期限はありません。
> - 同じキーで再送すると、プロジェクトが停止した後・同時実行の上限に達した後・その実行が終了した後であっても、**同じ実行**が返ります。
> - タイムアウトなどで成否が分からなくなった場合は、同じキーでそのまま再送してください。二重に実行されることはありません。
> - 別の実行を開始したい場合は、必ず新しいキーを採番してください。

同じキーで、違う `payload` か `config` を付けて再送すると `409 Conflict`（`origin_conflict`）が返ります。

#### エラーレスポンス

| ステータス | code                              | 説明                                                                                                                                                                                                                                                                                                                           |
| ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `idempotency_key_required`        | Idempotency-Key ヘッダーが無い                                                                                                                                                                                                                                                                                                      |
| `400` | `idempotency_key_invalid`         | Idempotency-Key の長さまたは文字種が不正                                                                                                                                                                                                                                                                                                 |
| `400` | `invalid_parameter`               | projectId が UUID の形式ではない                                                                                                                                                                                                                                                                                                     |
| `400` | `payload_too_large`               | payload を JSON の文字列にした長さが 8,000 文字を超える                                                                                                                                                                                                                                                                                       |
| `400` | `invalid_body`                    | リクエストボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                                                                                                                                                       |
| `413` | `body_too_large`                  | リクエストボディが 16 KiB を超過                                                                                                                                                                                                                                                                                                         |
| `415` | `unsupported_media_type`          | リクエストボディがあるのに、Content-Type が application/json ではない                                                                                                                                                                                                                                                                           |
| `404` | `project_not_found`               | プロジェクトが存在しない、またはアクセス権が無い                                                                                                                                                                                                                                                                                                     |
| `400` | `approvers_required`              | 有効な確認工程に確認担当者が設定されていない                                                                                                                                                                                                                                                                                                       |
| `409` | `unsupported_project_type`        | cycle 型のプロジェクトを指定した                                                                                                                                                                                                                                                                                                          |
| `409` | `project_inactive`                | プロジェクトが有効な状態ではない（一時停止中、またはアーカイブ済み）                                                                                                                                                                                                                                                                                           |
| `409` | `principal_suspended`             | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む                                                                                                                                                                                                                                                                |
| `409` | `start_step_in_branch_lane`       | 開始の工程が条件分岐のレーンの中にある。時間トリガーの開始する工程を、条件分岐のレーンの外の工程にしてください                                                                                                                                                                                                                                                                      |
| `409` | `definition_pending`              | プロジェクトの最初の定義が承認待ちの間は始められない。承認する人（ほかのオーナーか組織の管理者）が製品の画面で承認してから始めてください                                                                                                                                                                                                                                                         |
| `409` | `relink_required`                 | 取り込みで見つからなかった参照をつなぎ直すまで、プロジェクトを始められない・再開できない。プロジェクトの取得の relink と配置の relink に、残っている参照が出ます。起動を断る参照の外し方: kind が "agent" の行は Agent を置き直す（POST /v1/projects/{projectId}/placements）、kind が "connector" の行は製品の画面で連携先を保存し直す。blocking が false の行は実行を断らない、必要に応じて再度設定する項目で、DELETE /v1/projects/{projectId}/relink で消せますが、それだけでは始められません |
| `409` | `admin_stopped`                   | プロジェクト、またはプロジェクトに置いた登録 Agentを、管理者が止めている。再開は管理者に頼む（この API では再開できない）                                                                                                                                                                                                                                                           |
| `409` | `mixed_runtime`                   | 登録した Agent と、それ以外のエージェントが同じプロジェクトに置かれている                                                                                                                                                                                                                                                                                     |
| `409` | `agent_not_certified`             | 置いた登録 Agent に、ワークフローで使うための認定が無い                                                                                                                                                                                                                                                                                              |
| `409` | `lanes_not_for_marketplace`       | プロジェクトの流れにレーンがある（登録 Agent のプロジェクトはレーンで進められません）                                                                                                                                                                                                                                                                               |
| `400` | `invalid_parameter`               | 開始の入力の値が正しくない                                                                                                                                                                                                                                                                                                                |
| `400` | `missing_input`                   | 工程が必要とする入力ファイルが無い（前の工程が出していない、または指定していない）                                                                                                                                                                                                                                                                                    |
| `400` | `duplicate_target_path`           | 同じ置き先のパスに、2 つ以上の入力ファイルを置こうとしている                                                                                                                                                                                                                                                                                              |
| `400` | `mp_placement_not_in_snapshot`    | 工程の登録 Agent が、実行を始めたときの構成に含まれていない                                                                                                                                                                                                                                                                                            |
| `400` | `connection_version_missing`      | 接続のバージョンが保存されていない                                                                                                                                                                                                                                                                                                            |
| `400` | `invalid_runtime_config`          | 配置の実行の設定が、登録 Agent の定義に合わない                                                                                                                                                                                                                                                                                                  |
| `400` | `input_binding_cycle`             | 入力の受け渡しが循環している                                                                                                                                                                                                                                                                                                               |
| `400` | `input_binding_forward_reference` | まだ動いていない後の工程の出力を、入力に指定している                                                                                                                                                                                                                                                                                                   |
| `400` | `input_binding_unknown_output`    | 入力に指定した出力が、元の登録 Agent に無い                                                                                                                                                                                                                                                                                                    |
| `400` | `artifact_format_mismatch`        | 入力に指定した成果物の形式が、求める形式と違う                                                                                                                                                                                                                                                                                                      |
| `400` | `artifact_digest_missing`         | 入力に指定した成果物に digest が無い                                                                                                                                                                                                                                                                                                       |
| `400` | `invalid_config`                  | config の形が違う、知らない配置・工程を指している、設定が登録 Agent の定義に合わない、またはプロジェクトの工程に登録 Agent が置かれていない                                                                                                                                                                                                                                             |
| `409` | `artifact_not_ready`              | 入力に指定した成果物が、まだ使える状態ではない（または確認した内容と違う）。システム連携のトークンでは、プロジェクトの今のオーナーが上げ、まだ実行に結び付いていない下書きだけを指定できる                                                                                                                                                                                                                                |
| `409` | `origin_conflict`                 | 同じ Idempotency-Key で、違う payload か config を送った（同じ起点が、違う中身で使われている）                                                                                                                                                                                                                                                             |
| `409` | `connection_version_unavailable`  | 接続のバージョンを確かめられない（承認した後に、接続の対象または権限が変わった）                                                                                                                                                                                                                                                                                     |
| `429` | `too_many_active_runs`            | 同じプロジェクトで、実行中と確認待ちの実行が合わせて上限（3 件）に達している                                                                                                                                                                                                                                                                                      |

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

`cycle` 型のプロジェクトに設定された Webhook トリガーを発火し、対象のエージェントを**臨時に 1 回だけ**実行します。`workflow` 型に対して呼び出すと `404 Not Found` が返ります。

定期実行の設定はそのまま維持されます。発火による実行は、定期実行とは別に追加されるものです。発火は 1 件ずつ別に受け付けられ、先の発火に**まとまることはありません**。同じエージェント配置の同じ工程への発火は、受け付けた順に 1 件ずつ処理されます。

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                 |
| ----------- | -------- | -- | ------------------ |
| `projectId` | `string` | 必須 | プロジェクトの ID（UUID）   |
| `triggerId` | `string` | 必須 | 発火するトリガーの ID（UUID） |

#### リクエストボディ

| パラメータ     | 型        | 必須 | 説明                                                                                 |
| --------- | -------- | -- | ---------------------------------------------------------------------------------- |
| `eventId` | `string` | 必須 | 送信側が採番する一意な ID。同じ ID の再送は重複として扱われます。1〜160 文字で、使用できる文字は半角英数字と \_ . : @ + - です       |
| `payload` | `any`    | —  | エージェントへ渡す任意の JSON。JSON の文字列にして、エージェントへの依頼に添えて渡されます。文字列にしたときに 8,000 文字を超える部分は省略されます |

#### リクエスト例

**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)
```

#### レスポンスフィールド（202 Accepted）

| フィールド         | 型        | 説明                                                                                                                                                                                                                      |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result`      | `string` | "accepted"（新しく受け付けた）または "duplicate"（同じ eventId で受付済み）                                                                                                                                                                   |
| `jobId`       | `string` | 受付先のジョブ ID。エージェント配置と工程の組み合わせごとに決まり、同じ組み合わせへの発火では同じ値になります（発火ごとには変わりません）。実行状況の取得（GET /v1/projects/{projectId}/runs/{runId}）には使えません                                                                                        |
| `executionId` | `string` | 受け付けた巡回の実行の ID。実行の結果の取得・巡回の実行を止めるに使えます。同じ eventId の送り直しでも同じ値です（送り直しの応答には入らないことがあります。そのときは、発火で動いた実行の見分け方で探します）。動き出すまで（1 分ほどかかることがあります。同じエージェント配置の同じ工程に先の発火が待っていれば、その後）は、実行の結果の取得で 404 Not Found（execution\_not\_found）です |

#### レスポンス例

<!-- -->

<!-- -->

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

> **202 の意味**
>
> ここでの `202 Accepted` は、**受付を記録した**ことだけを表します。実行はこの後に行われ、その成否はこの応答に含まれません。実行の結果は含まないため、`202` を業務上の成功として扱わないでください。

#### 再送

冪等性はプロジェクト・トリガー・`eventId` の組み合わせで判定されます。同じ内容で再送すると `202` と `result: "duplicate"` が返ります。同じ `eventId` で `payload` が異なる場合は `409 Conflict`（`event_conflict`）が返ります。

#### エラーレスポンス

| ステータス | code                     | 説明                                                                          |
| ----- | ------------------------ | --------------------------------------------------------------------------- |
| `400` | `invalid_event_id`       | eventId が無い、または形式が不正                                                        |
| `400` | `invalid_parameter`      | projectId または triggerId が UUID の形式ではない                                      |
| `400` | `invalid_body`           | リクエストボディが壊れた JSON、または JSON のオブジェクトではない                                      |
| `415` | `unsupported_media_type` | リクエストボディがあるのに、Content-Type が application/json ではない                          |
| `404` | `trigger_not_found`      | プロジェクト・トリガーが存在しない、アクセス権が無い、Webhook ではないトリガーを指定した、または workflow 型のプロジェクトを指定した |
| `409` | `trigger_disabled`       | トリガーが無効化されている                                                               |
| `409` | `project_not_active`     | プロジェクトが実行可能な状態にない                                                           |
| `409` | `principal_suspended`    | プロジェクトを実行する人の利用を、管理者が止めている。管理者に、プロジェクトの持ち主を変更するか、利用の停止を解くよう頼む               |
| `409` | `admin_stopped`          | プロジェクト、または発火で動かす配置の Agent を、管理者が止めている。再開は管理者に頼む                             |
| `409` | `placement_unavailable`  | 発火対象のエージェント配置が存在しない、または実行できる状態にない                                           |
| `409` | `event_conflict`         | 同じ eventId で payload が異なる                                                   |
| `413` | `body_too_large`         | リクエストボディが 16 KiB を超過                                                        |
| `429` | `queue_full`             | 同じエージェント配置の同じ工程で実行を待っている発火が上限（20 件）に達している                                   |

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

実行の状況を取得します。API（`POST /v1/projects/{projectId}/runs`）で開始した実行のほか、<!-- -->画面・定期実行<!-- -->で始まった実行も取得できます。`cycle` 型のプロジェクトは実行（run）を作らないため、このエンドポイントの対象外です。

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明               |
| ----------- | -------- | -- | ---------------- |
| `projectId` | `string` | 必須 | プロジェクトの ID（UUID） |
| `runId`     | `string` | 必須 | 実行の ID（UUID）     |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                             | 型                | 説明                                                                                                                                                                                       |
| --------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`                           | `string`         | 実行の ID（UUID）                                                                                                                                                                             |
| `status`                          | `string`         | 実行の状態。"running"（実行中）/ "waiting\_gate"（確認待ち）/ "closed\_done"（完了）/ "closed\_rejected"（却下で終了）/ "closed\_failed"（失敗で終了）/ "cancelled"（中断）のいずれか。"running" と "waiting\_gate" 以外は、実行が終わったことを表します |
| `originType`                      | `string \| null` | 実行の始まり方。"manual"（画面から開始）/ "api"（API で開始）/ "cron"（定期実行）のいずれか                                                                                                                              |
| `originRef`                       | `string \| null` | 始まり方ごとの参照値。API で開始した実行では、開始したときの Idempotency-Key の値                                                                                                                                      |
| `currentStepId`                   | `string \| null` | 進んでいる工程の ID（UUID）。完了した実行では null。ほかの理由で終わった実行では、終わったときの工程の ID が残る場合があります                                                                                                                  |
| `startedByRef`                    | `string \| null` | 実行を始めたもの。値は下の「実行を始めたもの」の表のとおり                                                                                                                                                            |
| `actorLabel`                      | `string \| null` | 利用者ではない起動者の表示名（サービスアカウントの名前）。分からない場合と、それ以外は null                                                                                                                                         |
| `startedAt`                       | `string \| null` | 開始日時（ISO 8601）。開始前は null                                                                                                                                                                 |
| `endedAt`                         | `string \| null` | 終了日時（ISO 8601）。終了前は null                                                                                                                                                                 |
| `summary`                         | `string \| null` | 完了した実行で、出力が記録された最後の完了した工程の出力（先頭 2,000 文字）。そうした工程が無い場合と、完了していない実行では null                                                                                                                  |
| `runtimeKind`                     | `string \| null` | 実行環境の種類。"marketplace"（登録した Agent で動く実行）または "autonomous"。古い実行では null の場合があります                                                                                                             |
| `cancelRequestedAt`               | `string \| null` | 中断が求められた日時（ISO 8601）。求められていなければ null                                                                                                                                                     |
| `deadlineAt`                      | `string \| null` | ワークフローの実行の締め切り（ISO 8601）。締め切りが無ければ null                                                                                                                                                  |
| `configRevision`                  | `number \| null` | 案件設定のバージョン。登録した Agent で動く実行で使い、それ以外の実行では null                                                                                                                                            |
| `steps`                           | `array`          | 工程ごとの実行の記録。記録した順                                                                                                                                                                         |
| `steps[].runStepId`               | `string`         | 工程の実行の ID（"rs:" で始まる）                                                                                                                                                                    |
| `steps[].stepId`                  | `string \| null` | 工程の ID（UUID）                                                                                                                                                                             |
| `steps[].placementId`             | `string \| null` | その工程を担当した配置の ID（UUID）。Agent を動かさない行（確認の工程など）では null                                                                                                                                      |
| `steps[].executionId`             | `string \| null` | Agent の実行の ID。Agent を動かし始めると付きます                                                                                                                                                         |
| `steps[].conversationId`          | `string \| null` | Agent の実行の会話の ID。登録した Agent で動く実行では null                                                                                                                                                 |
| `steps[].status`                  | `string`         | "pending"（実行待ち）/ "running"（実行中）/ "waiting\_gate"（確認待ち）/ "done"（完了）/ "failed"（失敗）/ "skipped"（実行を省略）のいずれか                                                                                  |
| `steps[].attempt`                 | `number \| null` | 同じ回の中での再試行の回数（1 から）                                                                                                                                                                      |
| `steps[].lane`                    | `string \| null` | いつも "main"                                                                                                                                                                               |
| `steps[].scheduledAt`             | `string \| null` | 工程に時刻が設定されているとき、その時刻まで待つ行の予定日時（ISO 8601）。動き始めると null                                                                                                                                     |
| `steps[].startedAt`               | `string \| null` | 開始日時（ISO 8601）                                                                                                                                                                           |
| `steps[].endedAt`                 | `string \| null` | 終了日時（ISO 8601）                                                                                                                                                                           |
| `steps[].outputSummary`           | `string \| null` | 工程の出力の要約                                                                                                                                                                                 |
| `steps[].outcome`                 | `string \| null` | Agent の実行の結果。"completed" / "incomplete" / "failed" / "timeout" / "stopped" / "denied" / "skipped" のいずれか。結果の無い行では null                                                                    |
| `steps[].reasonCode`              | `string \| null` | 結果の理由コード。条件分岐で決められず人に選択してもらうときは "branch\_undecided"、条件分岐で選ばれなかったレーンの工程は "branch\_not\_selected"                                                                                          |
| `steps[].held`                    | `boolean`        | プロジェクトの一時停止で止めていて、再開を待っているか                                                                                                                                                              |
| `steps[].visit`                   | `number \| null` | この工程に来た何回目か（差し戻しで増えます）。記録の無い行では null                                                                                                                                                     |
| `steps[].reworkReason`            | `string \| null` | 差し戻しの理由                                                                                                                                                                                  |
| `steps[].gateFor`                 | `string \| null` | この確認の行が、どの工程の実行（runStepId）のために立ったか                                                                                                                                                       |
| `steps[].routedFrom`              | `string \| null` | 次の工程を決定して工程を飛ばしたとき、次の工程を決定した工程の実行（runStepId）                                                                                                                                             |
| `steps[].late`                    | `string \| null` | 結果が遅れて届き、進行に使わなかった理由                                                                                                                                                                     |
| `steps[].gate`                    | `object \| null` | 確認の要約。確認の工程の行に付きます。それ以外の行では null                                                                                                                                                         |
| `steps[].gate.decision`           | `string \| null` | "proceed"（進める）/ "send\_back"（差し戻す）/ "reject"（却下）のいずれか。決まっていなければ null                                                                                                                     |
| `steps[].gate.waitSource`         | `string \| null` | 何を待つ確認か。"human"（人の判断）/ "external"（外部の条件）                                                                                                                                                 |
| `steps[].resumeCommandId`         | `string \| null` | いつも null                                                                                                                                                                                 |
| `steps[].resumeReason`            | `string \| null` | いつも null                                                                                                                                                                                 |
| `steps[].supersededBy`            | `string \| null` | いつも null                                                                                                                                                                                 |
| `steps[].gateKind`                | `string \| null` | いつも null                                                                                                                                                                                 |
| `steps[].connectionConfirmOf`     | `string \| null` | いつも null                                                                                                                                                                                 |
| `plannedPlacements`               | `array`          | 開始したときの設定で、動く予定の工程と配置の並び                                                                                                                                                                 |
| `plannedPlacements[].stepId`      | `string \| null` | 工程の ID（UUID）                                                                                                                                                                             |
| `plannedPlacements[].placementId` | `string \| null` | 配置の ID（UUID）。確認の工程と Agent の無い工程では null                                                                                                                                                   |
| `lanes`                           | `array`          | いつも空の配列                                                                                                                                                                                  |

<!-- -->

##### 実行を始めたもの

| 始めたもの            | startedByRef                     | actorLabel                  |
| ---------------- | -------------------------------- | --------------------------- |
| 利用者（画面・API から開始） | 利用者 ID                           | null                        |
| サービスアカウント        | "client:" に続くサービスアカウントのクライアント ID | サービスアカウントの名前（分からない場合は null） |
| 定期実行             | null                             | null                        |

2026-09-25 より前にサービスアカウントが始めた実行では、`startedByRef` は null です。

#### レスポンス例

<!-- -->

<!-- -->

```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": []
}
```

#### エラーレスポンス

| ステータス | code                | 説明                                    |
| ----- | ------------------- | ------------------------------------- |
| `400` | `invalid_parameter` | projectId または runId が UUID の形式ではない    |
| `404` | `run_not_found`     | 実行が存在しない、別のプロジェクトの実行を指定した、またはアクセス権が無い |

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

実行中か確認待ちのワークフローの実行（`status` が `"running"`・`"waiting_gate"`）を中断します。画面の「中断する」と同じです。

中断すると、次のようになります。

- ワークフローの実行の `status` が `"cancelled"`（中断）になります。
  <!-- -->
  元に戻せません。
- <!-- -->
  まだ起動していない工程は起動されません。動いている工程の Agent には停止を伝えます（その工程の行の status は、止まるまで変わらないことがあります）。
  <!-- -->
- 確認工程の、まだ判断されていない確認依頼は取り下げられます。

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明                  |
| ----------- | -------- | -- | ------------------- |
| `projectId` | `string` | 必須 | プロジェクト ID（UUID）     |
| `runId`     | `string` | 必須 | ワークフローの実行の ID（UUID） |

#### リクエストボディ

| フィールド       | 型        | 必須 | 説明                                   |
| ----------- | -------- | -- | ------------------------------------ |
| `commandId` | `string` | 必須 | 送り直しを見分ける値（英数字と \_ . : - の 8〜128 文字） |
| `reason`    | `string` | —  | 中断の理由（500 文字まで）                      |

- 動いていないワークフローの実行（終わった後・中断した後）に送ると、何も変えずに `200 OK` が返り、`existing` が `true` です。中断した後に送り直したときも同じです。
- ほかの中断や、ワークフローの実行が終わるのと同じころに送ると、`202 Accepted` と `200 OK` の別と `existing` が、実際と合わないことがあります。結果は、ワークフローの実行の取得（`GET /v1/projects/{projectId}/runs/{runId}`）の `status` で確かめてください。
- `504 Gateway Timeout` は「中断されなかった」ことを意味しません。同じ `commandId` で送り直すか、ワークフローの実行の取得で `status` を確かめてください。

#### リクエスト例

**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": "入力データの誤りに気づいたため"
}'
```

**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': '入力データの誤りに気づいたため'},
)

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": "入力データの誤りに気づいたため"}),
}
);

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

**Go**

```go
payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "入力データの誤りに気づいたため"}`)
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)
```

#### レスポンスフィールド（202 Accepted / 200 OK）

この要求で新しく中断したときは `202 Accepted`、新しく中断しなかったときは `200 OK` です。

| フィールド               | 型                | 説明                                                 |
| ------------------- | ---------------- | -------------------------------------------------- |
| `runId`             | `string`         | ワークフローの実行の ID                                      |
| `status`            | `string`         | 送った後のワークフローの実行の状態（中断したときは "cancelled"）             |
| `cancelRequestedAt` | `string \| null` | 中断を受けた日時（ISO 8601）。中断されていないワークフローの実行では null        |
| `existing`          | `boolean`        | この要求で新しく中断しなかったとき true（202 Accepted のときはいつも false） |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                     | 説明                                                                               |
| ----- | ------------------------ | -------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | projectId・runId が UUID の形式ではない、commandId が無い・形の誤り、または reason が文字列ではない・500 文字を超える |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                |
| `404` | `run_not_found`          | ワークフローの実行が存在しない、ほかのプロジェクトのもの、またはアクセス権の無いプロジェクト                                   |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                 |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                        |

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

cycle のプロジェクトで、巡回の実行を止めます。画面の「停止する」と同じです。<!-- -->ボディは要りません（送っても使いません）。

- 止められるのは、cycle のプロジェクトの巡回の実行だけです。workflow の工程の実行（`rs:<数値>`）を指定すると `400 Bad Request`（`invalid_parameter`）です。ワークフローの実行は、[ワークフローの実行の中断](#cancel-run)で止めてください。
- 受け付けてから実行が止まるまで、1 分ほどかかることがあります。止まったかは、実行の結果の取得（`GET /v1/projects/{projectId}/executions/{executionId}`）で確かめてください。システム連携（サービスアカウント）のトークンでも呼べます（状態の項目だけを返します）。止める要求を受けたときに、まだ動き出していなかった実行は、実行の結果の取得で `404 Not Found`（`execution_not_found`）のままです。
- 前に止める要求を受けていた実行と、終わっていた実行は、何も変えずに `200 OK` が返り、`existing` が `true` です。

#### パスパラメータ

| パラメータ         | 型        | 必須 | 説明              |
| ------------- | -------- | -- | --------------- |
| `projectId`   | `string` | 必須 | プロジェクト ID（UUID） |
| `executionId` | `string` | 必須 | 巡回の実行の ID（UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（202 Accepted / 200 OK）

新しく止める要求を受けたときは `202 Accepted`、そうでないときは `200 OK` です。

| フィールド         | 型         | 説明                                                                                                                                                                                                |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executionId` | `string`  | 実行の ID                                                                                                                                                                                            |
| `state`       | `string`  | 受け付けたときの状態。止まったかどうかは表しません（確かめ方は、この節の初めの箇条にあります）。値の例: "dispatched"（動いている実行に止める要求を伝えた）、"cancelled"（まだ動き出していなかった実行を取り消した）、"terminal"（すでに終わっていた実行）。ほかにも、受け付けた時点の実行や送信の状態の値がそのまま入ります。値の一覧を決めて使わないでください |
| `existing`    | `boolean` | 前に止める要求を受けていた、または実行が終わっていたとき true（202 Accepted のときはいつも false）                                                                                                                                     |

#### レスポンス例

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

#### エラーレスポンス

| ステータス | code                     | 説明                                                                                            |
| ----- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | projectId が UUID の形式ではない、executionId が rs:<数値> でも UUID でもない、または executionId が workflow の工程の実行 |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                             |
| `404` | `execution_not_found`    | 実行が存在しない、ほかのプロジェクトの実行、cycle ではないプロジェクト、またはアクセス権の無いプロジェクト                                      |
| `413` | `body_too_large`         | ボディが 16 KiB を超える                                                                              |
| `415` | `unsupported_media_type` | ボディがあるのに、Content-Type が application/json ではない                                                 |

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

実行の状態（動いているか・終わったか・どう終わったか）を取得します。サービスアカウントのトークンでは、下の状態の項目だけを返します。アプリケーション（外部ツールでのログイン）のトークンで呼ぶと、[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#get-execution)の実行の結果の取得と同じ項目を返します。

- サイクルの巡回の実行は、トリガーの発火の応答の `executionId` で読めます。動き出すまで（1 分ほどかかることがあります）は `404 Not Found`（`execution_not_found`）です。巡回の実行を止めた後に、止まったかを確かめるときにも使います。
- workflow の工程の実行は、ワークフローの実行の取得の `steps[].executionId`（UUID）で読めます。応答の `executionId` は `rs:<数値>` で、この形の ID でも読めます。

#### パスパラメータ

| パラメータ         | 型        | 必須 | 説明                       |
| ------------- | -------- | -- | ------------------------ |
| `projectId`   | `string` | 必須 | プロジェクト ID（UUID）          |
| `executionId` | `string` | 必須 | 実行の ID（rs:<数値> または UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

サービスアカウントのトークンで呼んだときの項目です。

| フィールド         | 型                | 説明                                                                                                                                                                      |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `executionId` | `string`         | 実行の ID。workflow は rs:<数値>、cycle は UUID                                                                                                                                  |
| `kind`        | `string \| null` | "run\_step"（workflow の工程）または "sweep"（cycle の巡回）                                                                                                                         |
| `runId`       | `string \| null` | ワークフローの実行の ID。cycle は null                                                                                                                                              |
| `stepId`      | `string \| null` | 工程の ID                                                                                                                                                                  |
| `placementId` | `string \| null` | 配置の ID                                                                                                                                                                  |
| `attempt`     | `number \| null` | 試行の回数（基盤の失敗でやり直すと増えます。cycle は起動し直すと新しい実行になり、増えません）                                                                                                                      |
| `outcome`     | `string \| null` | 結果（[ユーザー API リファレンス（プロジェクト）の「結果の値」](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#execution-outcomes)） |
| `reasonCode`  | `string \| null` | 結果の理由。cycle は実行の終わり方の理由（例: "guardrail\_blocked"）、workflow は工程の報告の理由                                                                                                     |
| `resultState` | `string \| null` | "terminal"（結果あり）/ "running"（実行中）/ "missing"（記録不足）/ "unmeasured"（完遂を測っていない）/ "not\_applicable"（確認工程など、Agent の実行ではない行）                                                    |
| `terminal`    | `boolean`        | 終わっているかどうか                                                                                                                                                              |
| `startedAt`   | `string \| null` | 開始日時（ISO 8601）                                                                                                                                                          |
| `endedAt`     | `string \| null` | 終了日時（ISO 8601）                                                                                                                                                          |

#### エラーレスポンス

| ステータス | code                  | 説明                                                              |
| ----- | --------------------- | --------------------------------------------------------------- |
| `400` | `invalid_parameter`   | projectId が UUID の形式ではない、または executionId が rs:<数値> でも UUID でもない |
| `404` | `execution_not_found` | 実行が存在しない、ほかのプロジェクトの実行、まだ動き出していない巡回の実行、またはアクセス権の無いプロジェクト         |

#### レスポンス例

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

ワークフローの実行の成果物（開始で結んだ入力ファイルと、工程が作った出力）の一覧を、作られた順に全件取得します。中身は、成果物の中身の取得（`GET /v1/projects/{projectId}/artifacts/{artifactId}/content`）で読みます。<!-- -->サービスアカウントのトークンでは、この環境にあるすべてのプロジェクトの成果物を読めます。`run_id` が必要です。

#### パスパラメータ

| パラメータ       | 型        | 必須 | 説明              |
| ----------- | -------- | -- | --------------- |
| `projectId` | `string` | 必須 | プロジェクト ID（UUID） |

#### クエリパラメータ

| パラメータ    | 型        | デフォルト | 説明                     |
| -------- | -------- | ----- | ---------------------- |
| `run_id` | `string` | `—`   | 必須。ワークフローの実行の ID（UUID） |

#### リクエスト例

**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)
```

#### レスポンスフィールド（200 OK）

| フィールド                    | 型                | 説明                                     |
| ------------------------ | ---------------- | -------------------------------------- |
| `artifacts`              | `array`          | 成果物の配列                                 |
| `artifacts[].artifactId` | `string \| null` | 成果物の ID（UUID）                          |
| `artifacts[].runId`      | `string \| null` | ワークフローの実行の ID                          |
| `artifacts[].name`       | `string \| null` | 成果物の名前                                 |
| `artifacts[].mimeType`   | `string \| null` | 成果物の MIME タイプ                          |
| `artifacts[].size`       | `number \| null` | 大きさ（バイト）                               |
| `artifacts[].status`     | `string \| null` | "ready"（読める）または "uploading"（書き終わっていない） |
| `artifacts[].createdAt`  | `string \| null` | 作られた日時（ISO 8601）                       |
| `hasMore`                | `boolean`        | いつも false（全件を返します）                     |

#### レスポンス例

```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
}
```

#### エラーレスポンス

| ステータス | code                | 説明                                                    |
| ----- | ------------------- | ----------------------------------------------------- |
| `400` | `invalid_parameter` | projectId が UUID の形式ではない、または run\_id が無い・UUID の形式ではない |
| `404` | `project_not_found` | プロジェクトが存在しない                                          |
| `404` | `run_not_found`     | ワークフローの実行が存在しない、またはほかのプロジェクトのもの                       |

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

成果物の中身を取得します。`HEAD` でも呼べます。本文を除いて同じヘッダーが返るので、先に大きさを確かめられます。`GET` で読むと、記録 (証跡) に閲覧（`forensic.viewed`）が残ります（`HEAD` では残りません）。<!-- -->サービスアカウントのトークンで読んだときは、システム連携として残ります。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明                               |
| ------------ | -------- | -- | -------------------------------- |
| `projectId`  | `string` | 必須 | プロジェクト ID（UUID）                  |
| `artifactId` | `string` | 必須 | 成果物の ID（UUID）。成果物の一覧の artifactId |

#### リクエスト例

**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)
```

#### レスポンス（200 OK）

成果物の中身が、そのまま返ります。

| レスポンスヘッダー                | 説明                          |
| ------------------------ | --------------------------- |
| `Content-Type`           | 成果物の MIME タイプ               |
| `Content-Length`         | 大きさ（バイト）                    |
| `X-Content-Type-Options` | "nosniff"                   |
| `Content-Disposition`    | "attachment"（ダウンロードとして返します） |

#### エラーレスポンス

| ステータス | code                 | 説明                                                       |
| ----- | -------------------- | -------------------------------------------------------- |
| `400` | `invalid_parameter`  | projectId・artifactId が UUID の形式ではない                      |
| `404` | `artifact_not_found` | プロジェクトまたは成果物が存在しない、成果物がほかのプロジェクトのもの、またはワークフローの実行の成果物ではない |
| `409` | `artifact_not_ready` | 成果物がまだ書き終わっていない                                          |

### プロジェクト API の注意事項

| 項目             | 内容                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 404 の意味        | プロジェクトが存在しない場合とアクセス権が無い場合は、どのエンドポイントでも同じ `404 Not Found` が返り、どちらであるかは応答から区別できません。code はエンドポイントごとに決まっていて、実行の開始は `project_not_found`、トリガーの発火は `trigger_not_found`、実行状況の取得とワークフローの実行の中断は `run_not_found` です。成果物の一覧は `project_not_found`（実行が無いときは `run_not_found`）、成果物の中身の取得は `artifact_not_found` です。サイクルの巡回の実行の停止と実行の状態の取得は `execution_not_found` です。 |
| 型が対象外の場合       | 発火を `workflow` に対して呼んだ場合、および実行状況の取得とワークフローの実行の中断を `cycle` のプロジェクトに対して呼んだ場合は `404` です。サイクルの巡回の実行の停止を `workflow` のプロジェクトに対して呼んだ場合も `404` です。実行の開始を `cycle` に対して呼んだ場合だけは例外で、`409 unsupported_project_type` が返ります。                                                                                                                                      |
| リクエストボディ       | ボディを送る場合は、JSON オブジェクトにしてください。`Content-Type: application/json` 以外は `415`、壊れた JSON や JSON のオブジェクトではないボディは `400`（`invalid_body`）、16 KiB を超えるボディは `413` が返ります。                                                                                                                                                                                          |
| 未知のフィールド / クエリ | 仕様に無いフィールドやクエリパラメータは無視されます。仕様にあるクエリパラメータの値が不正な場合と、読めない `cursor` を指定した場合は `400 Bad Request` が返ります。                                                                                                                                                                                                                                                   |
| タイムアウト         | `504 Gateway Timeout` は「実行されなかったこと」を意味しません。実行の開始は同じ `Idempotency-Key` で、発火は同じ `eventId` と同じ本文で、ワークフローの実行の中断は同じ `commandId` で、そのまま再送してください。サイクルの巡回の実行の停止も、そのまま再送できます。                                                                                                                                                                                |

## エラーレスポンス

### HTTP ステータスコード

すべてのエンドポイントで返される可能性のある HTTP ステータスコードです。

| ステータス                        | 説明                                                                                                                                                                                        |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | リクエストパラメータが不正                                                                                                                                                                             |
| `401 Unauthorized`           | トークンが無効または未指定。管理者に利用を止められた利用者のトークンでも返ります（下の「利用を止められた利用者」）                                                                                                                                 |
| `403 Forbidden`              | リソースへのアクセス権限なし                                                                                                                                                                            |
| `404 Not Found`              | リソースが存在しない、または未定義のパス・メソッド（405 は返しません）                                                                                                                                                     |
| `409 Conflict`               | リソースが現在処理中など、操作が競合                                                                                                                                                                        |
| `409 Conflict`               | 組織の運用の役割（管理コンソールの「管理の役割」で付ける「運用」の役割）の人が、プロジェクトに参加せずに、その役割では使えない操作を呼んだ（`error.code` は `forbidden_role`）。待っても直りません。オーナーだけの操作は、プロジェクトのオーナーに頼んでください。ほかの操作は、オーナーにプロジェクトに加えてもらうと、参加の役割のとおりに呼べます |
| `413 Payload Too Large`      | リクエストボディがサイズ上限を超過                                                                                                                                                                         |
| `415 Unsupported Media Type` | リクエストボディの形式（Content-Type）に対応していない                                                                                                                                                         |
| `429 Too Many Requests`      | レート制限または同時実行の上限を超過。`error.type` は `rate_limit_error` で、`error.code` はエンドポイントにより異なります（例: 月間上限は `monthly_quota_exceeded`、プロジェクトの同時実行は `too_many_active_runs`）。時間をおいて再試行してください               |
| `500 Internal Server Error`  | サーバー内部エラー                                                                                                                                                                                 |
| `502 Bad Gateway`            | 上流サービス（認証基盤・チャット基盤等）との通信エラー                                                                                                                                                               |
| `503 Service Unavailable`    | サービス一時利用不可                                                                                                                                                                                |
| `504 Gateway Timeout`        | 上流サービスの応答タイムアウト                                                                                                                                                                           |

### エラーレスポンス形式

すべてのエラーレスポンスは以下の共通構造で返されます。

| フィールド                    | 型        | 説明                                                                                                                                                                                                                                       |
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.type`             | `string` | エラーの分類。"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` | 人間が読めるエラーメッセージ                                                                                                                                                                                                                           |
| `error.code`             | `string` | 機械的に処理可能なエラーコード（例: "missing\_parameter"、"invalid\_parameter"、"invalid\_token"）                                                                                                                                                           |
| `error.param`            | `string` | エラーの原因となったパラメータ名。バリデーションエラー時のみ含まれます                                                                                                                                                                                                      |
| `error.reason`           | `string` | 断りの理由の種類。プロジェクト API の 409（definition\_invalid）のときだけ含まれます                                                                                                                                                                                 |
| `error.suggested_action` | `string` | 推奨される対処方法。一部のエラーでのみ含まれます                                                                                                                                                                                                                 |

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

### 利用を止められた利用者

管理者に利用を止められた利用者のトークンで呼ぶと、`401 Unauthorized` が返ります。`error.code` は `account_suspended` です。

次の API は、利用を止められたかどうかを見ません: `GET /v1/organizations`・`GET /v1/job-types`・`GET /v1/user`・`PATCH /v1/user`・`GET /v1/marketplace-agents`、MCP の `list_agents` と、進行中のタスクが無いときの `cancel_chat`、登録 Agent の Agent Card（`GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json`）。
