# ユーザー API リファレンス（会話・ライブラリ・組織）

SaaS 版のユーザー向け API のエンドポイント仕様とエラーコードのリファレンスです。システム連携から呼ぶ API は [システム連携 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md) を参照してください。マーケットプレイス版は [システム連携 API リファレンス（マーケットプレイス版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/api-reference.md) を参照してください。

## ベース URL

すべての API リクエストは以下のベース URL に対して送信します。

SaaS

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

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

## 認証

すべてのAPIリクエストには、`Authorization` ヘッダーに Bearer トークンを含める必要があります。このページは、アプリケーション（Authorization Code フロー）で取ったトークンで呼ぶときの仕様です。システム連携（Client Credentials フロー）のトークンは chat のスコープを持てないため、チャットには使えません（プロジェクトの一部は呼べます。[システム連携 API リファレンス — プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md#projects)）。

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

トークンが無効または未指定の場合、`401 Unauthorized` が返されます。エンドポイントによっては追加のスコープが必要です。必要なスコープが不足している場合は `403 Forbidden` が返されます。

トークンの取得方法・スコープの詳細については、[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/auth-guide.md) および [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.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` よりそちらが先に返ります。

レスポンスには `x-request-id` ヘッダーが付きます。サービス側で採番する値で、リクエストで送った値は使われません。お問い合わせの際はこの値をお知らせください。

### ページネーション

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

| パラメータ    | 型         | 説明                                                                                   |
| -------- | --------- | ------------------------------------------------------------------------------------ |
| `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)・[ライブラリ](#library)・[Agent](#agents)・[スキル](#skills)・[プレイブック](#playbooks)・[プロジェクト一覧](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#projects) の各一覧エンドポイントです。`cursor` は不透明な値のため、内容を解釈せず、前回レスポンスの値をそのまま次のリクエストに指定してください。

スキルのバージョンの一覧（`GET /v1/skills/:skillId/versions`）はページネーションに対応していません。新しいバージョンから 100 個までを返し、`hasMore` はいつも `false` です。

## チャット

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

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

SSE ストリーミングガイド

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

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/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を指定します。省略すると新しい会話が作成されます。                                                                                                                                               |

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

SaaS

|                    |           |                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentLevel`       | `string`  | "default" または "high\_performance"。省略時は "default"。                                                                                                                                                                                                                                                                                                                   |
| `agentMode`        | `boolean` | エージェントモードの有効/無効。省略時は true。                                                                                                                                                                                                                                                                                                                                          |
| `privateMode`      | `boolean` | プライベートモードの有効/無効。省略時は false。                                                                                                                                                                                                                                                                                                                                         |
| `reportMode`       | `string`  | "with"（省略時）または "without"。完了時に作業報告書を生成するかを制御します。                                                                                                                                                                                                                                                                                                                     |
| `personaKey`       | `string`  | エージェントの応答人格（ペルソナ）を指定。`GET /v1/personas` が返す personaKey を指定します。省略時はペルソナを適用しません。一覧に無い値は 400 を返します。                                                                                                                                                                                                                                                                    |
| `playbookId`       | `string`  | 実行手順（プレイブック）を指定。`GET /v1/playbooks` が返す playbookId を指定します。省略時はプレイブックを適用しません。存在しない・無効化されている ID を指定した場合は 400 を返します。                                                                                                                                                                                                                                                   |
| `skillIds`         | `array`   | エージェントに読み込ませるスキルの ID 配列（最大 10 件）。`GET /v1/skills` が返す skillId を指定します。11 件以上を指定した場合は 400 を返します。存在しない ID や利用できない ID は無視され、残りのスキルで実行されます。                                                                                                                                                                                                                              |
| `outputFormat`     | `string`  | 応答テキストの形式。"plain"（省略時）は Markdown 記法を除去したプレーンテキスト（図は削除され、コードブロックは本文が残り、リンクは「文字 (URL)」になる）。"markdown" は Markdown 記法をそのまま保持する。                                                                                                                                                                                                                                         |
| `interactionReply` | `object`  | Agent の質問への答えの印。`{ interactionId, optionIndex? }` の形で、この会話で返事待ちの質問の `interactionId`（ストリーミングの `delta.interaction.interactionId`、または会話の履歴の `tasks[].metadata.interactionId`）と、選択肢から選んだ答えなら選んだ選択肢の番号（0〜9。最初が 0）を送ります。付けると、その質問への答えとして記録され、月の利用の枠の上限に達していても答えられます。`conversationId` と一緒に送ります。形が違う・知らない項目がある・この会話で返事待ちの質問の ID ではない・選択肢の外の番号のときは 400（`invalid_parameter`）。 |

#### 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 または filepath (string)` | アップロード済みファイルの `fileId`、または `GET /v1/library` が返す `filepath`（ライブラリファイル）のいずれか一方。1リクエストあたり合計最大20件 |

#### リクエスト例

**Create chat completion**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "model": "AGENTIC STAR",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "売上データを分析してください"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions",
  headers={
      "Authorization": f"Bearer {token}",
      "Content-Type": "application/json",
  },
  json={
      "model": "AGENTIC STAR",
      "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://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "AGENTIC STAR",
    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",
      "stream": true,
      "messages": []map[string]string{
          {"role": "user", "content": "売上データを分析してください"},
      },
  })

  req, _ := http.NewRequest("POST",
      "https://api.fd.agenticstar.tm.softbank.jp/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/saas/api/agent/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件を超過、reportMode が "with" / "without" 以外）。ボディが壊れた JSON（`code: "invalid_body"`）。または、指定した `conversationId` がアーカイブ済み（`code: "conversation_archived"`）。`interactionReply` の形が違う・知らない項目がある・この会話で返事待ちの質問の ID ではない・選択肢の外の番号（`code: "invalid_parameter"`。`param` は `interactionReply`、または `interactionReply.interactionId` のように `interactionReply.` を頭に付けた項目の名前）、または `interactionReply` を `conversationId` なしで送った（`code: "missing_parameter"`） |
| `400` | messages に user ロールのメッセージが 1 つも無い（`code: "no_user_message"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400` | personaKey が `GET /v1/personas` の一覧に無い（`code: "invalid_parameter"`・`param: "personaKey"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `400` | playbookId のプレイブックが存在しない（`code: "playbook_not_found"`）、または無効化されている（`code: "playbook_not_active"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `403` | chat:exec スコープが不足、または指定した会話がプロジェクトの会話（`code: "project_conversation"`。プロジェクトの会話には送れません）                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `404` | 指定した input\_file の `fileId` または `filepath` が見つからない（`code: "file_not_found"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409` | 指定した会話が現在処理中（`code: "conversation_processing"`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `403` | エージェントモードの依頼（agentMode が true。省略したときも true）を、管理者が許可していない（`code: "feature_not_permitted"`・`param: "agentMode"`）。agentMode を false にして送り直すか、管理者に許可を頼む                                                                                                                                                                                                                                                                                                                                                                                                 |
| `503` | 機能の許可を確かめられない（`code: "feature_permissions_unavailable"`）。時間をおいて送り直す                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

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

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

#### パスパラメータ

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

#### リクエスト例

**Resume SSE stream**

**curl**

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

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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/saas/api/agent/guide/streaming-guide.md)を参照してください。

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

| ステータス | code                 | 説明                                                       |
| ----- | -------------------- | -------------------------------------------------------- |
| `403` | `insufficient_scope` | chat:exec スコープが不足                                        |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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"`）                                                                                                                             |
| `403` | chat:exec スコープが不足                                                                                                                                                                                       |
| `404` | 会話が見つからない、またはメッセージを止められない（`code: "message_not_found"`）。`message_not_found` は、送った直後で 10 秒ほど待っても止められなかったとき（数秒後にもう一度送れば止まります）と、messageId のメッセージが無い、または自分のものではないとき（送り直しても止まりません。messageId を確かめてください）の 2 つです |
| `404` | messageId のメッセージが処理中ではない（すでに終わっている。`code: "not_processing"`）                                                                                                                                            |

## 会話管理

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

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

| メソッド   | エンドポイント                                                      | 説明                | スコープ (SaaS)                     |
| ------ | ------------------------------------------------------------ | ----------------- | ------------------------------- |
| GET    | `/v1/conversations`                                          | 会話一覧を取得           | `chat:history`                  |
| GET    | `/v1/conversations/:conversationId/messages`                 | メッセージ履歴を取得        | `chat:history`                  |
| GET    | `/v1/conversations/:conversationId/ui-resources/:toolCallId` | UI リソースの HTML を取得 | `chat:exec / a2a:all / mcp:all` |
| 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://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 が文字列ではない（複数回指定した場合など） |
| `403` | `insufficient_scope`        | chat:history スコープが不足                                                                                                                       |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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[].settings`                 | `object?`         | 利用者の発言（sender: "User"）を送ったときの設定。保存されている項目だけが入り、1 つも無ければ省略されます。各項目は送信（POST /v1/chat/completions）の同じ名前の項目と同じ意味です。アーカイブ済みの発言には付きません |
| `messages[].settings.agentLevel`      | `string?`         | "default" / "high\_performance"                                                                                                  |
| `messages[].settings.agentMode`       | `boolean?`        | エージェントモード                                                                                                                        |
| `messages[].settings.privateMode`     | `boolean?`        | プライベートモード                                                                                                                        |
| `messages[].settings.reportMode`      | `string?`         | "with" / "without"                                                                                                               |
| `messages[].settings.personaKey`      | `string \| null?` | ペルソナのキー。ペルソナを選ばずに送ったときは null                                                                                                     |
| `messages[].settings.playbookId`      | `string?`         | Playbook の ID                                                                                                                    |
| `messages[].settings.skillIds`        | `string[]?`       | Skill の ID の配列                                                                                                                   |
| `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/saas/api/agent/guide/streaming-guide.md) を参照 |
| `files`          | `array?`  | タスクに関連するファイル（`filename` / `size` / `filepath` / `mimeType?` の構造。MIME タイプ判定不能時は `mimeType` を省略）。タスクに関連ファイルがない場合は配列自体が省略される                                                   |
| `timestamp`      | `number`  | タスク実行時のタイムスタンプ（Unix ミリ秒）                                                                                                                                                    |
| `createdAt`      | `string`  | 作成日時（ISO 8601）                                                                                                                                                              |
| `updatedAt`      | `string`  | 更新日時（ISO 8601）                                                                                                                                                              |

#### UI リソース（`tasks[].metadata.uiResource`）

エージェントが実行中に UI（グラフ・地図・カード一覧など）を生成した場合、そのメタ情報が該当タスクの `metadata.uiResource` に含まれます。**HTML 本体は含まれません**。取得するには [UI リソース取得エンドポイント](#get-ui-resource)を使用します。

オブジェクトの構造は SSE と同一です。フィールドの詳細は [ストリーミングガイド — delta.uiResource](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-uiresource) を参照してください。代替テキストは**同じタスクの `content`** に入ります（SSE では同じチャンクの `delta.content`）。

| metadata の内容                      | 意味                                                                                                                                                                                       |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uiResource` のみ                   | 表示専用の UI。ユーザーの回答は不要です                                                                                                                                                                    |
| `uiResource` + `interaction_type` | 回答を求める UI。`interaction_type` は `"choice"` または `"question"`。この形は `origin: "first-party"` に限られます                                                                                           |
| `interaction_type` のみ             | 回答を求めるが UI は含まれない場合。`interaction_type` は `"choice"` \| `"confirmation"` \| `"question"` のいずれか。回答方法は同じタスクの `content` に入ります                                                                |
| `options`                         | 選択肢の配列（最大10件、各200文字以下）。`interaction_type` の有無とは独立に含まれることがあります                                                                                                                            |
| `interactionId`                   | Agent の質問の ID。付かない場合があります（画面の部品で尋ねる質問など）。この質問がまだ返事待ちなら、次の Chat API・MCP の `interactionReply` に使えます                                                                                        |
| `draft`                           | チャットで作った下書き。`uiResource` と一緒に入ります。形と作り方は [ストリーミングガイド — delta.draft](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-draft) を参照してください |

> **判別方法が SSE と異なります**
>
> SSE では `delta.uiResource`（表示専用）と `delta.interaction.uiResource`（入力系）が構造で分かれますが、履歴・検索では**どちらも `tasks[].metadata.uiResource` に入ります**。判別には `metadata.interaction_type` の有無を使ってください。

```json
{
  "status": "completed",
  "content": "売上は3四半期連続で増加しています",
  "metadata": {
    "uiResource": {
      "type": "html",
      "origin": "first-party",
      "altText": "売上は3四半期連続で増加しています",
      "uri": "ui://widget/chart",
      "server_name": "agentic-star-widgets",
      "tool_name": "widget_chart",
      "tool_call_id": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
      "mime_type": "text/html;profile=mcp-app"
    }
  },
  "timestamp": 1788007347240
}
```

`size` は履歴・検索では含まれません。

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

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

**リクエスト例**

**curl**

```bash
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50" \
-H "Authorization: Bearer <access_token>"

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://api.fd.agenticstar.tm.softbank.jp/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/saas/api/agent/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" 以外    |
| `403` | `insufficient_scope`      | chat:history スコープが不足                                                          |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |

### GET`/v1/conversations/:conversationId/ui-resources/:toolCallId`

UI リソースの HTML を取得します。SSE の [`delta.uiResource`](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-uiresource)、履歴・検索の [`tasks[].metadata.uiResource`](#history-ui-resource)、A2A・MCP の各応答に含まれる `tool_call_id` を指定します。

対象は `type: "html"` の UI リソースのみです。`type: "data"` は応答にペイロードがインラインで含まれるため、このエンドポイントを呼ぶ必要はありません。

> **応答は JSON です**
>
> このエンドポイントは HTML を `Content-Type: text/html` で返しません。ブラウザで直接開いて描画させるためのものではなく、**利用者のアプリケーションが HTML を取得するための口**です。

#### 必要スコープ

`chat:exec` / `a2a:all` / `mcp:all` のいずれか1つが必要です。UI リソースを受け取った経路のスコープでそのまま取得できます。**`chat:history` は対象外**のため、履歴 API だけを利用しているクライアントは別途いずれかのスコープが必要です。

#### パスパラメータ

| パラメータ            | 型        | 必須 | 説明                                                                   |
| ---------------- | -------- | -- | -------------------------------------------------------------------- |
| `conversationId` | `string` | 必須 | 会話のID（UUID）                                                          |
| `toolCallId`     | `string` | 必須 | UI リソースの識別子。uiResource.tool\_call\_id の値。形式は英数字・ハイフン・アンダースコアの1〜128文字 |

#### リクエスト例

**Get UI resource**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/ui-resources/chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
response = requests.get(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/{conversation_id}/ui-resources/{tool_call_id}",
  headers={"Authorization": f"Bearer {token}"},
)

resource = response.json()
html = resource["html"]
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/${conversationId}/ui-resources/${toolCallId}`,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const resource = await response.json();
const html = resource.html;
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/"+conversationID+"/ui-resources/"+toolCallID,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

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

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

| フィールド        | 型        | 説明                                                                            |
| ------------ | -------- | ----------------------------------------------------------------------------- |
| `toolCallId` | `string` | リクエストで指定した UI リソースの識別子                                                        |
| `type`       | `string` | `"html"` 固定                                                                   |
| `origin`     | `string` | `"first-party"`（AGENTIC STAR が生成）または `"external"`（管理者が接続を許可した外部の MCP サーバーが生成） |
| `mimeType`   | `string` | HTML の MIME タイプ。通常は `"text/html;profile=mcp-app"`                             |
| `html`       | `string` | HTML のソース                                                                     |

#### レスポンス例

```json
{
  "toolCallId": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
  "type": "html",
  "origin": "first-party",
  "mimeType": "text/html;profile=mcp-app",
  "html": "<!doctype html><html>...</html>"
}
```

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

`code` でリトライの可否を判断できます。

| ステータス | code                      | 説明                                                                | リトライ       |
| ----- | ------------------------- | ----------------------------------------------------------------- | ---------- |
| `400` | `invalid_conversation_id` | conversationId が全部 0 の UUID（00000000-0000-0000-0000-000000000000） | 不可         |
| `400` | `invalid_parameter`       | toolCallId の形式が不正                                                 | 不可         |
| `403` | `insufficient_scope`      | chat:exec / a2a:all / mcp:all のいずれも持っていない                         | 不可         |
| `404` | `not_found`               | 該当する UI リソースが存在しない                                                | 不可         |
| `404` | `conversation_not_found`  | 会話が存在しない、または他のユーザーの会話                                             | 不可         |
| `404` | `file_too_large`          | HTML の実体が 512KB を超えており返却できない                                      | 不可（永続的な失敗） |
| `502` | `upstream_api_error`      | 一時的な取得失敗                                                          | 可          |
| `500` | `internal_error`          | その他のエラー                                                           | 可          |

> **描画時の注意**
>
> このエンドポイントが返すのは **HTML の文字列**で、**描画は利用者のアプリケーション側で行います**。サンドボックス化の要否や `origin` による違いは、[ストリーミングガイド — 描画時の注意](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#rendering-notes) を参照してください。

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

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

#### パスパラメータ

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

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

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

#### リクエスト例

**Update conversation**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 ではない                                     |
| `403` | `insufficient_scope`      | chat:history スコープが不足                                                          |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |

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

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

#### パスパラメータ

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

#### リクエスト例

**Delete conversation**

**curl**

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

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` を使用                      |
| `403` | `insufficient_scope`      | chat:history スコープが不足                                                          |
| `404` | `conversation_not_found`  | 会話が見つからない、または自分の会話ではない                                                        |
| `409` | `conversation_processing` | 会話が現在処理中のため削除できない                                                             |
| `409` | `project_conversation`    | プロジェクトの会話。プロジェクトの会話は削除できません                                                   |
| `409` | `claw_bound_conversation` | Claw の予定に結び付いた会話。先にアプリで、この会話に結び付いた Claw の予定を削除してください                          |
| `409` | `legal_hold`              | 保全中の会話。管理者が保全を解除するまで削除できません                                                   |
| `503` | `claw_binding_unverified` | Claw の予定に結び付いているかを確かめられなかった。時間をおいて再試行してください                                   |

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

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

#### パスパラメータ

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

#### リクエスト例

**Restore archived conversation**

**curl**

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

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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）。この値は受け付けません |
| `403` | `insufficient_scope`      | chat:history スコープが不足                                                          |
| `404` | `conversation_not_found`  | アーカイブに該当会話が存在しない、または既に active（archive 状態と区別されません）                             |

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

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

SaaS 版では、プロジェクトの外の個人のスケジュールと Claw は、最後に読んだ後に続けて終わった回が 3 回以上あり、そのいちばん古い回が 14 日以上前になると、止まることがあります（プロジェクトの巡回は対象外です）。API で結果を読んでいて止めたくないときは、この API で既読にしてください。画面でその会話を開いても既読になります。

#### パスパラメータ

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

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

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

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

#### リクエスト例

**Mark a conversation as read**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/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 でない                                                      |
| `403` | `insufficient_scope`      | chat:history スコープが不足                                                          |
| `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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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` | `insufficient_scope`              | chat:file スコープが不足                                                               |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/files?order=desc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \
-H "Authorization: Bearer <access_token>"

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://api.fd.agenticstar.tm.softbank.jp/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" 以外 |
| `403` | `insufficient_scope` | chat:file スコープが不足         |

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

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

#### パスパラメータ

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

#### リクエスト例

**Download file**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 が不正なフォーマット                                          |
| `403` | `insufficient_scope`  | chat:file スコープが不足                                          |
| `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://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 が不正なフォーマット |
| `403` | `insufficient_scope` | chat:file スコープが不足 |
| `404` | `file_not_found`     | ファイルが見つからない       |

## 成果物取得

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

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

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

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

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

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

`chat:exec` / `a2a:all` / `mcp:all` のいずれか1つがあれば取得できます。A2A の artifact や MCP のツール応答で得た成果物も、**その経路のスコープのまま**このエンドポイントで取得できます。

<!-- -->

<!-- -->

プロジェクトの実行の結果・確認依頼の材料のファイル（`files[].filepath`）は、このエンドポイントではなく、[プロジェクトのファイルの中身の取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#get-project-file-content)（`GET /v1/projects/{projectId}/files/content`）で取得します。

<!-- -->

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

| パラメータ        | 型        | 必須 | 説明                                                                                 |
| ------------ | -------- | -- | ---------------------------------------------------------------------------------- |
| `path`       | `string` | 必須 | 成果物のファイルパス（メッセージ履歴の deliverables\[].filepath で取得）                                  |
| `version_id` | `string` | —  | ファイルのバージョンの ID（ファイルライブラリのバージョンの一覧 GET /v1/library/versions の versionId）。省くと今のバージョン |

#### リクエスト例

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

**Get artifact file**

**curl**

```curl
FILEPATH='<filepath>'

curl --get "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 の形の段が無い）                              |
| `403` | `insufficient_scope`  | chat:exec / a2a:all / mcp:all のいずれも持っていない                  |
| `404` | `not_found`           | ファイルが見つからない（保存先の応答に別の code があるときはその code）                  |
| `500` | `unknown`             | 保存先の不明な誤り                                                  |
| `500` | `storage_forbidden`   | 保存先へのアクセスが拒否された。管理者に連絡してください                               |
| `500` | `rejected`            | 保存先がリクエストを断った。管理者に連絡してください                                 |
| `503` | `rate_limited`        | 保存先が一時的に混んでいる。時間をおいて再試行してください                              |
| `503` | `transient`           | 保存先が一時的に使えない。時間をおいて再試行してください                               |
| `503` | `service_unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください |

## ライブラリ

ユーザーのライブラリファイル（アップロード済みファイルおよびエージェントが生成した成果物）を横断的に一覧します。取得した `filepath` は Chat の `input_file` 添付や成果物取得（`GET /v1/files/proxy`）でのダウンロードに使用できます。

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

| メソッド | エンドポイント                | 説明                    | スコープ (SaaS) |
| ---- | ---------------------- | --------------------- | ----------- |
| GET  | `/v1/library`          | ライブラリファイル一覧を取得        | `chat:exec` |
| GET  | `/v1/library/versions` | ライブラリファイルのバージョンの一覧を取得 | `chat:exec` |

### GET`/v1/library`

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

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

| パラメータ    | 型         | デフォルト    | 説明                                           |
| -------- | --------- | -------- | -------------------------------------------- |
| `limit`  | `integer` | `50`     | 取得件数（1〜100）                                  |
| `cursor` | `string`  | `—`      | 次ページ取得用カーソル（前回レスポンスの cursor 値）               |
| `search` | `string`  | `—`      | ファイル名で絞り込み（部分一致）                             |
| `source` | `string`  | `—`      | "agent"（エージェント生成）または "user"（ユーザーアップロード）で絞り込み |
| `order`  | `string`  | `"desc"` | "asc" または "desc"                             |

#### リクエスト例

**List library files**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library?source=agent&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）

| フィールド                    | 型         | 説明                                                             |
| ------------------------ | --------- | -------------------------------------------------------------- |
| `files`                  | `array`   | ライブラリファイルオブジェクトの配列                                             |
| `files[].filename`       | `string`  | ファイル名                                                          |
| `files[].filepath`       | `string`  | ファイルパス（Chat の input\_file 添付や GET /v1/files/proxy でのダウンロードに使用） |
| `files[].source`         | `string`  | "agent"（エージェント生成）または "user"（ユーザーアップロード）                        |
| `files[].createdAt`      | `string`  | 作成日時（ISO 8601）                                                 |
| `files[].updatedAt`      | `string`  | 最終更新日時（ISO 8601）                                               |
| `files[].mimeType`       | `string?` | MIME タイプ。判定できない場合は省略                                           |
| `files[].size`           | `number?` | ファイルサイズ（バイト）。取得できない場合は省略                                       |
| `files[].conversationId` | `string?` | 関連する会話 ID。成果物が会話に紐づく場合のみ含まれます                                  |
| `hasMore`                | `boolean` | 次のページが存在するかどうか                                                 |
| `cursor`                 | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                          |

#### レスポンス例

```json
{
  "files": [
    {
      "filename": "report.xlsx",
      "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
      "source": "agent",
      "createdAt": "2026-03-14T10:30:00.000Z",
      "updatedAt": "2026-03-14T10:30:00.000Z",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 20480,
      "conversationId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                                                                                  |
| ----- | --------------------------------------------------------------------------------------------------- |
| `400` | limit（1〜100の範囲外）、cursor、source（"agent" / "user" 以外）、order（"asc" / "desc" 以外）、または search（文字列ではない）が不正 |
| `403` | chat:exec スコープが不足                                                                                   |

### GET`/v1/library/versions`

ライブラリファイル 1 件のバージョンの一覧を、新しい順に取得します。すべてのバージョンを返し、`hasMore` はいつも `false` です。バージョンの中身は、成果物取得（`GET /v1/files/proxy`）の `version_id` に `versionId` を渡して取得します。バージョンの記録が無いファイルでは、`versions` は空の配列で、`currentVersionId` は null です。

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

| パラメータ  | 型        | デフォルト | 説明                                     |
| ------ | -------- | ----- | -------------------------------------- |
| `path` | `string` | `—`   | 必須。ファイルのパス（GET /v1/library の filepath） |

#### リクエスト例

**List library file versions**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions",
  headers={"Authorization": f"Bearer {token}"},
  params={"path": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions" + "?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
{
  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/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx", 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）

| フィールド                  | 型                | 説明                           |
| ---------------------- | ---------------- | ---------------------------- |
| `filepath`             | `string`         | ファイルのパス                      |
| `currentVersionId`     | `string \| null` | 今のバージョンの ID。バージョンが無いときは null |
| `versions`             | `array`          | バージョンの配列（新しい順）               |
| `versions[].versionId` | `string \| null` | バージョンの ID                    |
| `versions[].size`      | `number \| null` | 大きさ（バイト）                     |
| `versions[].createdAt` | `string \| null` | バージョンができた日時（ISO 8601）        |
| `versions[].isCurrent` | `boolean`        | 今のバージョンかどうか                  |
| `hasMore`              | `boolean`        | いつも false                    |

#### レスポンス例

```json
{
  "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
  "currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
  "versions": [
    {
      "versionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
      "size": 20480,
      "createdAt": "2026-03-14T10:30:00.000Z",
      "isCurrent": true
    },
    {
      "versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
      "size": 18944,
      "createdAt": "2026-03-13T08:00:00.000Z",
      "isCurrent": false
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                                                      |
| ----- | ----------------------------------------------------------------------- |
| `400` | path が無い・空（`code: "invalid_parameter"`）                                 |
| `403` | chat:exec スコープが不足                                                       |
| `404` | ファイルが見つからない、または自分のファイルではない（`code: "not_found"`）                         |
| `502` | サービスの内部で一時的な誤りが起きた（`code: "upstream_connection_error"`）。時間をおいて送り直してください |

## Agent・Playbook・Skill の共通の決まり

Agent・Playbook・Skill を読む・作る・変える・消す・コピーする API に共通の決まりです。システム連携のトークンでは呼べません（呼ぶと `403 Forbidden`（`forbidden`））。

| 操作       | スコープ                                             | 対象                                           | 対象外のとき                                                                                           |
| -------- | ------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| 読む       | `assets:read`（スキル・プレイブックの一覧は `chat:exec` でも呼べます） | 自分のものと、公開されているもの                             | ほかの利用者の非公開のもの・存在しないものは `404 Not Found`（`agent_not_found`・`playbook_not_found`・`skill_not_found`） |
| 作る・コピーする | `assets:write`                                   | —                                            | —                                                                                                |
| 変える      | `assets:write`                                   | 自分のものだけ                                      | ほかの利用者のものは `404 Not Found`                                                                       |
| 消す       | `assets:delete`                                  | 自分のものだけ（システム管理者は、ほかの利用者が公開したプレイブック・スキルも消せます） | ほかの利用者のものは `404 Not Found`                                                                       |

- ほかの利用者のものを直したいときは、自分のものにコピーしてから直します。
- 変えるときは、取得の `digest` を `baseDigest` に入れて送ります。取得した後にほかの変更が入っていると `409 Conflict`（`stale_base`）が返ります。取得し直してから送り直してください。
- JSON のボディは 3 MiB までです。超えると `413 Payload Too Large`（`body_too_large`）が返ります。スキルのファイルを送る API の上限は、その API の説明を参照してください。
- Agent の API は、SSO でログインしていない利用者のトークンでは `403 Forbidden`（`sso_required`）が返ります。

送り直したときの扱いは次のとおりです。

| API                                             | 送り直しを見分けるもの                | 同じもので送り直すと                                                                                                |
| ----------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
| 作る                                              | —                          | もう 1 つ作られます。応答が届かなかったときは、一覧の ID と `createdAt` で作られたかを確かめてから送り直してください                                      |
| コピーする                                           | `Idempotency-Key` ヘッダー（任意） | 1 回目のコピーが返り、もう 1 つは作られません。付けないときは、作ると同じく、送り直すともう 1 つ作られます（マーケットプレイス版の登録 Agent のコピーは除きます。Agent のコピーの説明を参照） |
| スキルの文書を書き換える（`PATCH /v1/skills/:skillId/files`） | `Idempotency-Key` ヘッダー（任意） | 新しいバージョンを作らずに、1 回目にできたバージョンが返ります                                                                          |

### スキル・プレイブックの公開の承認

テナントの管理者が、スキル・プレイブックの公開に管理者の承認を要るとしているときは、`isShared: true` を送っても公開されず、公開の承認待ちになります（画面の「公開を申請」と同じです）。承認・差し戻しは、管理者が管理コンソールで行います。承認が要るかどうかは API では読めません。公開されたか承認待ちになったかは、応答の `isShared` と `shareRequestStatus` で確かめてください。

自分のスキル・プレイブックの一覧・取得と、作る・変える・コピーの応答には、次の申請の状態の項目が入ります。公開の一覧と、ほかの利用者の公開のものの取得には入りません。ただし、スキルの文書を書き換える応答の `skill` には `sharePendingListing` は入りません（スキルの取得で読めます）。

| フィールド                   | 型                | 説明                                                                                                  |
| ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `shareRequestStatus`    | `string \| null` | "pending"（承認待ち）/ "rejected"（差し戻し）/ null（申請していない）                                                    |
| `shareRequestNote`      | `string \| null` | 申請の理由                                                                                               |
| `shareReviewNote`       | `string \| null` | 管理者のコメント（差し戻したときなど）                                                                                 |
| `shareRequestedAt`      | `string \| null` | 申請した日時（ISO 8601）                                                                                    |
| `sharePendingVersionId` | `string \| null` | スキルだけ。承認を待っているバージョンの ID                                                                             |
| `sharePendingListing`   | `object \| null` | スキルだけ。承認を待っているカテゴリ・タグ。承認待ちの変更として記録された項目（category・tags）が入ります（承認の前に公開中の値に戻したときも、その項目は残ります）。無いときは null |

- **申請の理由**（`shareRequestNote`）: スキルを作る・ファイルを丸ごと入れ替える・設定を変える、プレイブックを作る・変えるで送れます。前後の空白を除いて 2000 文字までです（超えると `400 Bad Request`（`invalid_parameter`））。空の文字列・空白だけ・null は、送らないのと同じです。理由は、申請になったときにだけ残ります。承認が要らなかったとき（承認を要るとしていないテナント）は使われません。どちらになったかは、応答の `shareRequestStatus`・`isShared` で分かります。
- **理由だけは変えられません**: 承認待ちのものに、中身を変えずに今と違う理由を送ると `400 Bad Request`（`invalid_parameter`）です。理由を変えるときは、申請を取り下げてから再申請してください。今と同じ理由なら、送り直しとして受け付けます。
- **取り下げ**: 承認待ちのものに `isShared: false` を送ります（スキルは設定を変える、プレイブックはプレイブックを変えるで送ります）。
- **公開中のスキルの新しいバージョン**: 公開の承認が有効なテナントで、公開中のスキルのファイルを変えると、新しいバージョンは承認待ちになり、承認されるまで前のバージョンが使われます。
- **公開中のスキルのカテゴリ・タグ**: 公開の承認が有効なテナントで、公開中のスキルのカテゴリ・タグを変える（スキルの設定を変える）と、変えた値は承認待ちになり、承認されるまでスキルの `category`・`tags` は前の値のままです。承認待ちの値は `sharePendingListing` で読めます。同じ更新で `isShared: false` を送ったときは、承認待ちにならず、すぐに変わって非公開になります。
- **公開中のプレイブックの中身**: 公開の承認が有効なテナントで、公開中のプレイブックの中身（名前・説明・カテゴリ・タグ・手順）を変えると、公開は続いたまま（`isShared` は `true` のまま）、変えた中身の申請になります（`shareRequestStatus` が `"pending"`）。承認されるまで、ほかの利用者には承認した中身が見えます（公開の一覧・取得・コピー）。自分の取得と、自分の Agent・チャットは、変えた後の中身を使います。公開している中身に戻すと、申請は取り下げられます。差し戻された後は、`isShared: true` を送ると（中身を変えなくても）再申請します。

## Agent

プロジェクトの工程に配置して動かす Agent を、ライブラリの資産として扱います。Agent の ID（`agentId`）は、プロジェクトに配置したときの配置の ID とは別の値です。

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

| メソッド   | エンドポイント                    | 説明                              | スコープ (SaaS)     |
| ------ | -------------------------- | ------------------------------- | --------------- |
| GET    | `/v1/agents`               | 自分の Agent の一覧を取得                | `assets:read`   |
| GET    | `/v1/agents/shared`        | 公開されている Agent の一覧を取得            | `assets:read`   |
| GET    | `/v1/agents/:agentId`      | Agent を取得                       | `assets:read`   |
| POST   | `/v1/agents`               | Agent を作る                       | `assets:write`  |
| PATCH  | `/v1/agents/:agentId`      | Agent を変える                      | `assets:write`  |
| DELETE | `/v1/agents/:agentId`      | Agent を消す                       | `assets:delete` |
| POST   | `/v1/agents/:agentId/copy` | 公開されている Agent を自分の Agent としてコピー | `assets:write`  |

### GET`/v1/agents`

自分の Agent の一覧を取得します。最終更新日時の降順（新しい順）で返ります。カーソルベースのページネーションに対応しています。公開されている Agent の一覧（`GET /v1/agents/shared`）も、クエリパラメータ・レスポンスは同じです。

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

| パラメータ    | 型         | デフォルト | 説明                             |
| -------- | --------- | ----- | ------------------------------ |
| `q`      | `string`  | `—`   | 名前・説明・ゴールの一部で絞り込み（100 文字まで）    |
| `limit`  | `integer` | `50`  | 1 ページの取得件数（1-100）              |
| `cursor` | `string`  | `—`   | 次ページ取得用カーソル（前回レスポンスの cursor 値） |

#### リクエスト例

**List agents**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents?q=受注&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）

| フィールド     | 型         | 説明                                             |
| --------- | --------- | ---------------------------------------------- |
| `agents`  | `array`   | Agent オブジェクトの配列。各項目は Agent の取得の digest 以外と同じです |
| `hasMore` | `boolean` | 次のページが存在するかどうか                                 |
| `cursor`  | `string`  | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます          |

#### レスポンス例

```json
{
  "agents": [
    {
      "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
      "name": "受注データの取り込み",
      "description": "受注メールから受注データを作る",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "isShared": false,
      "shareScope": "all",
      "shareOrganizations": null,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "spec": {
        "goal": "受信した受注メールから、受注データの表を作ってください。",
        "guardrail": "外部のサービスへは送信しない。",
        "skills": [
          {
            "skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
            "name": "order-parser",
            "versionId": null
          }
        ],
        "playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
        "inputFiles": [
          {
            "type": "blob",
            "filepath": "/path/to/orders-template.xlsx",
            "filename": "orders-template.xlsx"
          }
        ],
        "agentLevel": "default",
        "orgId": null,
        "jobRole": null,
        "agentConfig": null,
        "exposureConsent": null
      },
      "projectCount": 1,
      "copyCount": 0,
      "createdAt": "2026-09-20T02:10:00.000Z",
      "updatedAt": "2026-09-28T15:18:02.255Z",
      "adminStop": null
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                                                                                                              |
| ----- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400` | limit（1〜100 の範囲外）、cursor、または q（文字列ではない、100 文字を超える）が不正（code は invalid\_parameter）                                                |
| `403` | assets:read スコープが不足（code は insufficient\_scope）、システム連携のトークンで呼び出した（code は forbidden）、または SSO でログインしていない利用者（code は sso\_required） |

### GET`/v1/agents/shared`

公開されている Agent の一覧を取得します（自分が公開したものも含みます）。組織だけに公開された Agent は、その組織の利用者にだけ出ます。クエリパラメータ・レスポンス・エラーは、自分の Agent の一覧と同じです。

#### リクエスト例

**List shared agents**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared?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)
```

### GET`/v1/agents/:agentId`

Agent を取得します。自分の Agent と、公開されている Agent を取得できます。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明               |
| --------- | -------- | -- | ---------------- |
| `agentId` | `string` | 必須 | Agent の ID（UUID） |

#### リクエスト例

**Get agent**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
{
  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/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b", 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）

| フィールド                        | 型                 | 説明                                                                                                    |
| ---------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------- |
| `agentId`                    | `string`          | Agent の ID（UUID）                                                                                      |
| `name`                       | `string \| null`  | 名前                                                                                                    |
| `description`                | `string \| null`  | 説明                                                                                                    |
| `ownerUserId`                | `string \| null`  | 持ち主の利用者 ID                                                                                            |
| `isShared`                   | `boolean \| null` | 公開しているかどうか                                                                                            |
| `shareScope`                 | `string \| null`  | 公開の範囲。"all"（全員）または "organizations"（shareOrganizations の組織の利用者だけ）                                      |
| `shareOrganizations`         | `array \| null`   | 公開先の組織のコードの配列。shareScope が "organizations" のときに使います                                                   |
| `runtimeKind`                | `string \| null`  | 実行環境の種類。"autonomous"、またはマーケットプレイス版の登録 Agent は "marketplace"                                           |
| `marketplaceAgentId`         | `string \| null`  | マーケットプレイス版の登録 Agent の ID。それ以外は null                                                                   |
| `spec`                       | `object`          | Agent の定義                                                                                             |
| `spec.goal`                  | `string \| null`  | ゴール（指示）                                                                                               |
| `spec.guardrail`             | `string \| null`  | ガードレール                                                                                                |
| `spec.skills`                | `array`           | 使うスキル                                                                                                 |
| `spec.skills[].skillId`      | `string \| null`  | スキル ID                                                                                                |
| `spec.skills[].name`         | `string \| null`  | スキル名                                                                                                  |
| `spec.skills[].versionId`    | `string \| null`  | 固定したスキルのバージョンの ID。固定していない場合は null で、いつもその時点のバージョンを使います                                                |
| `spec.playbookId`            | `string \| null`  | 使うプレイブックの ID                                                                                          |
| `spec.inputFiles`            | `array`           | 入力ファイル                                                                                                |
| `spec.inputFiles[].type`     | `string \| null`  | 入力ファイルの種類。ライブラリのファイルは "blob"。定期実行から作った Agent では "git"・"upload" が入っていることがあります                          |
| `spec.inputFiles[].filepath` | `string \| null`  | ファイルのパス。"blob" は GET /v1/library の filepath と同じ形。"git"・"upload" は保存された参照の先頭に / を付けた値で、ライブラリのパスではありません |
| `spec.inputFiles[].filename` | `string \| null`  | ファイル名                                                                                                 |
| `spec.agentLevel`            | `string \| null`  | "default" または "high\_performance"                                                                     |
| `spec.orgId`                 | `string \| null`  | 実行のときに使う組織のコード                                                                                        |
| `spec.jobRole`               | `string \| null`  | 実行のときに使う職種のコード                                                                                        |
| `spec.agentConfig`           | `object \| null`  | 今は使っていない項目です（値が入っていても使われません）                                                                          |
| `spec.exposureConsent`       | `object \| null`  | 今は使っていない項目です（値が入っていても使われません）                                                                          |
| `projectCount`               | `number \| null`  | この Agent を配置しているプロジェクトの数（消したプロジェクトの配置は数えません）                                                          |
| `copyCount`                  | `number \| null`  | コピーされた回数                                                                                              |
| `adminStop`                  | `object \| null`  | 管理者が止めているときの、停止元・理由・時刻。止めていなければ null。一覧と取得で返ります                                                       |
| `adminStop.source`           | `string \| null`  | 停止元。"aster"（AGENTIC STAR の管理者）、または連携先の "agent365"・"aws"                                               |
| `adminStop.reasonCode`       | `string \| null`  | 理由の種類。"admin"（管理者が止めた）・"remote\_stopped"（連携先で止められた）・"remote\_unreachable"（連携先に届かない）                   |
| `adminStop.reason`           | `string \| null`  | 理由の文。自分の Agent のときだけ入ります（ほかの利用者の Agent では null）                                                       |
| `adminStop.stoppedAt`        | `string \| null`  | 止めた時刻（ISO 8601）                                                                                       |
| `createdAt`                  | `string \| null`  | 作成日時（ISO 8601）                                                                                        |
| `updatedAt`                  | `string \| null`  | 最終更新日時（ISO 8601）                                                                                      |
| `digest`                     | `string`          | Agent を変えるときに baseDigest に送る値。名前・説明・公開・公開の範囲・公開先の組織・定義から作られ、配置しているプロジェクトの数・コピー数・日時では変わりません            |

#### レスポンス例

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "受注データの取り込み",
  "description": "受注メールから受注データを作る",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "受信した受注メールから、受注データの表を作ってください。",
    "guardrail": "外部のサービスへは送信しない。",
    "skills": [
      { "skillId": "cb62d540-5439-4748-99f0-961b8de91a78", "name": "order-parser", "versionId": null }
    ],
    "playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
    "inputFiles": [
      { "type": "blob", "filepath": "/path/to/orders-template.xlsx", "filename": "orders-template.xlsx" }
    ],
    "agentLevel": "default",
    "orgId": null,
    "jobRole": null,
    "agentConfig": null,
    "exposureConsent": null
  },
  "projectCount": 1,
  "copyCount": 0,
  "createdAt": "2026-09-20T02:10:00.000Z",
  "updatedAt": "2026-09-28T15:18:02.255Z",
  "digest": "1aKrerEIdHNpFSBa9TkuXycB1Q6oD2NUX18-uGPiPLg"
}
```

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

| ステータス | 説明                                                                                                                              |
| ----- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400` | agentId が UUID の形式ではない（code は invalid\_parameter）                                                                               |
| `403` | assets:read スコープが不足（code は insufficient\_scope）、システム連携のトークンで呼び出した（code は forbidden）、または SSO でログインしていない利用者（code は sso\_required） |
| `404` | Agent が存在しない、またはほかの利用者の非公開の Agent（code は agent\_not\_found）                                                                     |

### POST`/v1/agents`

Agent を作ります。

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

| フィールド             | 型         | 必須 | 説明                                                                                                                                                                                                                                                                                                        |
| ----------------- | --------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | `string`  | 必須 | 名前（255 文字まで。空にはできません）                                                                                                                                                                                                                                                                                     |
| `description`     | `string`  | —  | 説明（5000 文字まで）                                                                                                                                                                                                                                                                                             |
| `isShared`        | `boolean` | —  | 公開するかどうか。省くと非公開                                                                                                                                                                                                                                                                                           |
| `spec`            | `object`  | 必須 | Agent の定義                                                                                                                                                                                                                                                                                                 |
| `spec.goal`       | `string`  | 必須 | ゴール（指示）。5000 文字まで。空白だけにはできません                                                                                                                                                                                                                                                                             |
| `spec.guardrail`  | `string`  | —  | ガードレール。5000 文字まで                                                                                                                                                                                                                                                                                          |
| `spec.skills`     | `array`   | —  | 使うスキル。\[{ skillId, versionId? }] の形で、自分のスキルか公開されているスキル（有効なもの）を 10 個まで。versionId を付けるとそのバージョンに固定し、省くか null にするといつもその時点のバージョンを使います。ほかの利用者のスキルの versionId は、公開されたことのあるバージョンだけです（スキルのバージョンの一覧で返る範囲）。取得の spec.skills をそのまま送れます（name は無視します）。同じスキルを重ねて指定できません                                                   |
| `spec.playbookId` | `string`  | —  | 使うプレイブックの ID。自分のプレイブックだけ                                                                                                                                                                                                                                                                                  |
| `spec.inputFiles` | `array`   | —  | 入力ファイル。\[{ type, filepath, filename? }] の形で 10 個まで。type は "blob"（自分のライブラリのファイル。filepath は GET /v1/library の filepath）です。定期実行から作った Agent では "git"・"upload" が入っていることがあり、取得した値をそのまま送れます。filepath は先頭の / を除いて空にはできません。filename は 255 文字までの文字列か null です。付いている入力ファイルは、実行のときにそのまま渡ります（プロジェクトの持ち主のファイルでなくても外れません） |
| `spec.agentLevel` | `string`  | —  | "default" または "high\_performance"                                                                                                                                                                                                                                                                         |
| `spec.orgId`      | `string`  | —  | 実行のときに使う組織のコード（255 文字まで）                                                                                                                                                                                                                                                                                  |
| `spec.jobRole`    | `string`  | —  | 実行のときに使う職種のコード（255 文字まで）                                                                                                                                                                                                                                                                                  |

`description` と、`spec` の `goal` 以外の項目は、`null` を送ると省いたのと同じ扱いです（`spec.skills`・`spec.inputFiles` は空になります）。

`spec.skillIds`・`spec.skillVersions` は受け付けません（送ると `400`、`invalid_parameter`）。スキルは `spec.skills` で指定してください。

#### リクエスト例

**Create agent**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "受注データの取り込み",
  "description": "受注メールから受注データを作る",
  "spec": {
    "goal": "受信した受注メールから、受注データの表を作ってください。",
    "guardrail": "外部のサービスへは送信しない。",
    "skills": [
      {
        "skillId": "cb62d540-5439-4748-99f0-961b8de91a78"
      }
    ],
    "agentLevel": "default"
  }
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': '受注データの取り込み', 'description': '受注メールから受注データを作る', 'spec': {'goal': '受信した受注メールから、受注データの表を作ってください。', 'guardrail': '外部のサービスへは送信しない。', 'skills': [{'skillId': 'cb62d540-5439-4748-99f0-961b8de91a78'}], 'agentLevel': 'default'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "受注データの取り込み", "description": "受注メールから受注データを作る", "spec": {"goal": "受信した受注メールから、受注データの表を作ってください。", "guardrail": "外部のサービスへは送信しない。", "skills": [{"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"}], "agentLevel": "default"}}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "受注データの取り込み", "description": "受注メールから受注データを作る", "spec": {"goal": "受信した受注メールから、受注データの表を作ってください。", "guardrail": "外部のサービスへは送信しない。", "skills": [{"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"}], "agentLevel": "default"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents", 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)
```

#### レスポンス（201 Created）

Agent の取得と同じ形（`adminStop` を除きます。一覧と取得で確かめてください）で、作った Agent を返します。ほかに `removedSkillIds`（string\[]）が付きます。使えなくなっていて外して保存したスキル（消された・止められた・公開がやめられた・固定したバージョンが無い、または公開されていない）の ID です。外していなければ空です。

#### レスポンス例

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "受注データの取り込み",
  "description": "受注メールから受注データを作る",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "受信した受注メールから、受注データの表を作ってください。",
    "guardrail": "外部のサービスへは送信しない。",
    "skills": [
      {
        "skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
        "name": "order-parser",
        "versionId": null
      }
    ],
    "playbookId": null,
    "inputFiles": [],
    "agentLevel": "default",
    "orgId": null,
    "jobRole": null,
    "agentConfig": null,
    "exposureConsent": null
  },
  "projectCount": 0,
  "copyCount": 0,
  "createdAt": "2026-09-20T02:10:00.000Z",
  "updatedAt": "2026-09-28T15:18:02.255Z",
  "digest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
  "removedSkillIds": []
}
```

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

| ステータス | code                     | 説明                                                                                                                                                                                                                     |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | name・spec が無い、name・description・isShared の型や長さの誤り、name が空白だけ、spec がオブジェクトではない、spec.playbookId が UUID の形式ではない、spec.skills の形の誤り（skillId・versionId が UUID の形式ではない、同じスキルを重ねた など）、または spec.skillIds・spec.skillVersions を送った |
| `400` | `invalid_spec`           | spec.goal が無い・空白だけ、spec の文字列の項目の型や長さの誤り、spec.agentLevel が選べる値ではない、spec.inputFiles の形の誤り（type が "blob"・"git"・"upload" 以外、filepath が空、filename が 255 文字を超える など）、またはスキル・入力ファイルが 10 個を超える                                  |
| `400` | `playbook_not_found`     | spec.playbookId が自分のプレイブックではない                                                                                                                                                                                         |
| `400` | `skill_not_found`        | spec.skills のスキルが、自分のスキルでも公開されている有効なスキルでもない                                                                                                                                                                            |
| `400` | `version_not_found`      | spec.skills の versionId が、そのスキルのバージョンではない、またはほかの利用者のスキルで見せていないバージョン（スキルのバージョンの一覧で返らないもの）                                                                                                                               |
| `400` | `file_not_found`         | spec.inputFiles の type が "blob" のファイルが、自分のライブラリにない                                                                                                                                                                     |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                                                      |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                                                                                                                                                                   |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                                                                                                                                      |
| `403` | `sso_required`           | SSO でログインしていない利用者                                                                                                                                                                                                      |
| `413` | `body_too_large`         | ボディが 3 MiB を超える                                                                                                                                                                                                        |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                                                                                                                                              |

### PATCH`/v1/agents/:agentId`

自分の Agent を変えます。送った項目だけを変えます。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明               |
| --------- | -------- | -- | ---------------- |
| `agentId` | `string` | 必須 | Agent の ID（UUID） |

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

| フィールド                | 型         | 必須 | 説明                                                                                                                                                   |
| -------------------- | --------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`         | `string`  | 必須 | Agent の取得の digest                                                                                                                                    |
| `name`               | `string`  | —  | 名前（255 文字まで。空にはできません）                                                                                                                                |
| `description`        | `string`  | —  | 説明（5000 文字まで。空の文字列・空白だけ・null にはできません）                                                                                                                |
| `isShared`           | `boolean` | —  | 公開するかどうか                                                                                                                                             |
| `shareScope`         | `string`  | —  | 公開の範囲。"all"（全員）または "organizations"（shareOrganizations の組織の利用者だけ）                                                                                     |
| `shareOrganizations` | `array`   | —  | 公開先の組織のコード（20 件まで。1 件 255 文字まで。前後の空白を除き、同じ値は 1 つにします）。送ると全部が置き換わります。公開していて範囲が "organizations" のときと、shareScope の "organizations" と一緒に送るときは、1 件以上が要ります |
| `spec`               | `object`  | —  | Agent の定義。送った項目だけを今の定義に重ねます（skills・inputFiles は配列ごと置き換わります）。項目は Agent を作るときと同じです。項目に null を送ると、その項目を外します（skills・inputFiles は空になります）。goal は外せません      |

name・description・isShared・shareScope・shareOrganizations・spec のうち、少なくとも 1 つを送ってください。

`spec` を変えるときは、送っていない項目も含めて、定義が指すプレイブック・入力ファイルと、新しく付けたスキル（バージョンを変えたスキルを含みます）を確かめます。プレイブックは自分のもの、スキルは有効で自分のものか公開されているもの、入力ファイルは自分のライブラリにあるものでないと `400` が返ります。前から付いているスキルは、使えなくなっていても `400` にせず、外して保存し、`removedSkillIds` で返します。コピーした Agent は、ほかの利用者のプレイブック・スキル・入力ファイルを指していることがあります（公開されていて有効なスキルは、コピーしても元のスキルを指します。そのスキルの公開がやめられると使えなくなります）。そのときは、自分のものに変えてください。

#### リクエスト例

**Update agent**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
  "description": "受注メールから受注データの表を作る"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs', 'description': '受注メールから受注データの表を作る'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs", "description": "受注メールから受注データの表を作る"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs", "description": "受注メールから受注データの表を作る"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b", 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)
```

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

Agent の取得と同じ形（`adminStop` を除きます。一覧と取得で確かめてください）で、変えた後の Agent（新しい `digest`）を返します。ほかに `removedSkillIds`（string\[]）が付きます。使えなくなっていて外して保存したスキル（消された・止められた・公開がやめられた・固定したバージョンが無い、または公開されていない）の ID です。外していなければ空です。

#### レスポンス例

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "受注データの取り込み",
  "description": "受注メールから受注データの表を作る",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "受信した受注メールから、受注データの表を作ってください。",
    "guardrail": "外部のサービスへは送信しない。",
    "skills": [
      {
        "skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
        "name": "order-parser",
        "versionId": null
      }
    ],
    "playbookId": null,
    "inputFiles": [],
    "agentLevel": "default",
    "orgId": null,
    "jobRole": null,
    "agentConfig": null,
    "exposureConsent": null
  },
  "projectCount": 0,
  "copyCount": 0,
  "createdAt": "2026-09-20T02:10:00.000Z",
  "updatedAt": "2026-09-28T15:18:02.255Z",
  "digest": "NhoPOFZIlKaF-GPh9VCRdVUAFqIZpE3OX1wt-BKdtu0",
  "removedSkillIds": []
}
```

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

| ステータス | code                           | 説明                                                                                                                                                                                                                                                                |
| ----- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`            | agentId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、name・description・isShared の型や長さの誤り、name が空白だけ、description を空の文字列・空白だけ・null にした、spec がオブジェクトではない、spec.playbookId が UUID の形式ではない、spec.skills の形の誤り（同じスキルを重ねた など）、または spec.skillIds・spec.skillVersions を送った |
| `400` | `invalid_spec`                 | spec.goal を null・空白だけにした、spec の文字列の項目の型や長さの誤り、spec.agentLevel が選べる値ではない、spec.inputFiles の形の誤り（type が "blob"・"git"・"upload" 以外、filepath が空、filename が 255 文字を超える など）、またはスキル・入力ファイルが 10 個を超える                                                                       |
| `400` | `playbook_not_found`           | 定義のプレイブックが自分のプレイブックではない                                                                                                                                                                                                                                           |
| `400` | `skill_not_found`              | 新しく付けたスキル（バージョンを変えたスキルを含みます）が、自分のスキルでも公開されている有効なスキルでもない（前から付いているスキルは、外して保存し、removedSkillIds で返します）                                                                                                                                                                |
| `400` | `version_not_found`            | 新しく付けたスキル・バージョンを変えたスキルの versionId が、そのスキルのバージョンではない、またはほかの利用者のスキルで見せていないバージョン（スキルのバージョンの一覧で返らないもの）。バージョンを変えずに残した固定が使えなくなっていれば、外して保存し、removedSkillIds で返します                                                                                                        |
| `400` | `file_not_found`               | 定義の入力ファイル（type が "blob" のもの）が、自分のライブラリにない                                                                                                                                                                                                                         |
| `400` | `runtime_not_allowed`          | マーケットプレイス版の登録 Agent は変えられない                                                                                                                                                                                                                                       |
| `400` | `invalid_share_scope`          | shareScope が "all"・"organizations" ではない                                                                                                                                                                                                                           |
| `400` | `invalid_share_organizations`  | shareOrganizations が配列ではない、21 件以上、または文字列でない・空・空白だけ・256 文字以上の値がある                                                                                                                                                                                                  |
| `400` | `share_organizations_required` | shareScope に "organizations" と空の shareOrganizations を送った、または公開している（送った値か今の値の isShared が true）のに、範囲が "organizations" で組織が 1 件も無い（送った値と今の値を合わせて見ます）                                                                                                                 |
| `400` | `invalid_body`                 | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                                                                                                                                                                                 |
| `403` | `insufficient_scope`           | assets:write スコープが不足                                                                                                                                                                                                                                              |
| `403` | `forbidden`                    | システム連携のトークンで呼び出した                                                                                                                                                                                                                                                 |
| `403` | `sso_required`                 | SSO でログインしていない利用者                                                                                                                                                                                                                                                 |
| `404` | `agent_not_found`              | Agent が存在しない、またはほかの利用者の Agent                                                                                                                                                                                                                                     |
| `409` | `stale_base`                   | 取得した後に Agent が変わっている                                                                                                                                                                                                                                              |
| `413` | `body_too_large`               | ボディが 3 MiB を超える                                                                                                                                                                                                                                                   |
| `415` | `unsupported_media_type`       | ボディの Content-Type が application/json ではない                                                                                                                                                                                                                         |

### DELETE`/v1/agents/:agentId`

自分の Agent を消します。消した Agent は、配置していたプロジェクトから外れ、その配置の巡回も止まります。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明               |
| --------- | -------- | -- | ---------------- |
| `agentId` | `string` | 必須 | Agent の ID（UUID） |

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

| パラメータ   | 型        | デフォルト     | 説明                                                           |
| ------- | -------- | --------- | ------------------------------------------------------------ |
| `force` | `string` | `"false"` | "true" を指定すると、配置しているプロジェクトがあっても消します。"true" / "false" 以外は 400 |

#### リクエスト例

**Delete agent**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
  headers={"Authorization": f"Bearer {token}"},
  params={"force": "false"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b" + "?force=false",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

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

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "deleted": true
}
```

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

| ステータス | code                 | 説明                                                     |
| ----- | -------------------- | ------------------------------------------------------ |
| `400` | `invalid_parameter`  | agentId が UUID の形式ではない、または force が "true" / "false" 以外 |
| `403` | `insufficient_scope` | assets:delete スコープが不足                                  |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                      |
| `403` | `sso_required`       | SSO でログインしていない利用者                                      |
| `404` | `agent_not_found`    | Agent が存在しない、またはほかの利用者の Agent                          |
| `409` | `agent_in_use`       | Agent を配置しているプロジェクトがある（force=true で、配置から外して消せます）       |
| `409` | `agent_running`      | この Agent の巡回が実行中                                       |
| `409` | `admin_stopped`      | 管理者がこの Agent を止めている                                    |

### POST`/v1/agents/:agentId/copy`

公開されている Agent を、自分の Agent としてコピーします。新しく作るコピーは非公開です。ボディは不要です（送っても読みません）。

定義はそのまま写ります。定義が指すプレイブック・スキル・入力ファイルは、コピーする人が使えるように、次のように直します。

- **プレイブック**: 自分のもの以外は、自分のプレイブックとして複製し、複製を指します。公開の承認が有効なテナントでは、公開されていないものは複製せずに外します。公開中のものは、承認した中身を複製します
- **スキル**: 自分のものと、公開されていて有効なものは、そのまま指します（元の Agent がバージョンを指定していればそのバージョンを、指定していなければ持ち主の今のバージョンを使います）。公開されているスキルにバージョンを指定しているときは、公開されたことのあるバージョンだけをそのまま指します。それ以外は、使っているバージョンを自分のスキルとして複製し、複製を指します。公開の承認が有効なテナントでは、公開されていないか無効なスキル（公開されたことの無いバージョンを指定しているものを含む）は、複製せずに外します
- **入力ファイル**: 複製しません。自分のライブラリに無いものは外します
- 見つからないプレイブック・スキルは外します

定義をこの形に直せないとき（自分の無効なスキルを指しているときなど）は、プレイブック・スキル・入力ファイルを全部外して写します。マーケットプレイス版の登録 Agent では、同じ登録 Agent の自分の Agent が既にあれば、新しく作らずにそれを返します。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明                     |
| --------- | -------- | -- | ---------------------- |
| `agentId` | `string` | 必須 | コピーする Agent の ID（UUID） |

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

| ヘッダー              | 必須 | 説明                                                                     |
| ----------------- | -- | ---------------------------------------------------------------------- |
| `Idempotency-Key` | —  | 送り直しを見分けるキー（英数字と \_ . : - の 8〜128 文字）。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します |

#### リクエスト例

**Copy agent**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: copy-agent-20261118-0001"
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-agent-20261118-0001"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "copy-agent-20261118-0001",
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-agent-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### レスポンス（201 Created）

Agent の取得と同じ形（`adminStop` を除きます。一覧と取得で確かめてください）に次の 3 つを足して、コピーして作った Agent を返します。マーケットプレイス版の登録 Agent では、既にある自分の Agent を返すことがあります（そのときの応答の `projectCount` は `0` です。配置しているプロジェクトの数は取得で確かめてください）。

| フィールド                | 型          | 説明                                                                                                                                         |
| -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `duplicated`         | `object`   | 自分のものとして複製した数（playbooks: プレイブックの数、skills: スキルの数）                                                                                           |
| `strippedInputFiles` | `string[]` | 入力ファイルを外したとき（定義を直せずに全部外したときも）、コピーした Agent の名前が 1 つ入ります。外していなければ空です。外したファイルの名前ではありません                                                       |
| `strippedResources`  | `string[]` | 公開の承認が有効なテナントで、公開されていないプレイブック、または公開されていないか無効なスキル（公開されたことの無いバージョンの固定を含む）を外したとき、コピーした Agent の名前が 1 つ入ります。外していなければ空です。外したプレイブック・スキルの名前ではありません |

同じ `Idempotency-Key` で送り直したときは、`200 OK` で、1 回目のコピーを同じ形で返します。このとき `duplicated` は 0 件、`strippedInputFiles`・`strippedResources` は空です（送り直しでは新しく複製しないため）。1 回目のコピーが消されていると `404 Not Found`（`agent_not_found`）が返ります。新しいキーで送ってください。

#### レスポンス例

```json
{
  "agentId": "2c9d4e6f-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
  "name": "受注データの取り込み",
  "description": "受注メールから受注データを作る",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "受信した受注メールから、受注データの表を作ってください。",
    "guardrail": "外部のサービスへは送信しない。",
    "skills": [
      {
        "skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
        "name": "order-parser",
        "versionId": null
      }
    ],
    "playbookId": "2f6a8c0e-4b1d-4a3c-9e5f-7d9b1a3c5e70",
    "inputFiles": [
      {
        "type": "blob",
        "filepath": "/path/to/orders-template.xlsx",
        "filename": "orders-template.xlsx"
      }
    ],
    "agentLevel": "default",
    "orgId": null,
    "jobRole": null,
    "agentConfig": null,
    "exposureConsent": null
  },
  "projectCount": 0,
  "copyCount": 0,
  "createdAt": "2026-09-20T02:10:00.000Z",
  "updatedAt": "2026-09-28T15:18:02.255Z",
  "digest": "SBD5evHBJXCLMJy93n5V7KQJQn9o_NmbPmvgYSQFLSo",
  "duplicated": {
    "playbooks": 1,
    "skills": 0
  },
  "strippedInputFiles": [],
  "strippedResources": []
}
```

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

| ステータス | code                      | 説明                                                                                 |
| ----- | ------------------------- | ---------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`       | agentId が UUID の形式ではない                                                             |
| `400` | `idempotency_key_invalid` | Idempotency-Key の形式が誤っている                                                          |
| `403` | `insufficient_scope`      | assets:write スコープが不足                                                               |
| `403` | `forbidden`               | システム連携のトークンで呼び出した                                                                  |
| `403` | `sso_required`            | SSO でログインしていない利用者                                                                  |
| `404` | `agent_not_found`         | Agent が存在しない、ほかの利用者の非公開の Agent、または同じ Idempotency-Key で作ったコピーが消されている（新しいキーで送ってください） |
| `409` | `already_owned`           | 自分の Agent をコピーしようとした                                                               |
| `409` | `idempotency_conflict`    | 同じ Idempotency-Key で、別の Agent のコピーを送った                                             |
| `409` | `admin_stopped`           | 管理者がこの Agent を止めている                                                                |

## スキル

スキルを読む・作る・変える・消す・コピーします。`skillId` は、Chat の `skillIds` パラメータに指定してエージェントにスキルを読み込ませるときや、Agent の定義（`spec.skills`）に使います。共通の決まりは [Agent・Playbook・Skill の共通の決まり](#assets-common) を参照してください。

スキルは、`SKILL.md` と付属のファイル（文書・スクリプト・設定値のファイルなど）でできています。ファイルを変えるたびに新しいバージョンができ、前のバージョンも残ります。

自分が登録したスキルは `GET /v1/skills`、公開されているスキル（自分が公開したものを含む）は `GET /v1/skills/shared` で取得します。公開スキルはコピーせずそのまま `skillIds` に指定できます。

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

| メソッド   | エンドポイント                             | 説明                | スコープ (SaaS)               |
| ------ | ----------------------------------- | ----------------- | ------------------------- |
| GET    | `/v1/skills`                        | 自分のスキル一覧を取得       | `chat:exec / assets:read` |
| GET    | `/v1/skills/shared`                 | 公開されているスキル一覧を取得   | `chat:exec / assets:read` |
| GET    | `/v1/skills/:skillId`               | スキルを取得            | `assets:read`             |
| GET    | `/v1/skills/:skillId/versions`      | スキルのバージョンの一覧を取得   | `assets:read`             |
| GET    | `/v1/skills/:skillId/files`         | スキルのファイルの一覧を取得    | `assets:read`             |
| GET    | `/v1/skills/:skillId/files/content` | スキルの 1 ファイルを取得    | `assets:read`             |
| GET    | `/v1/skills/:skillId/download`      | スキルのファイルを zip で取得 | `assets:read`             |
| POST   | `/v1/skills`                        | スキルを作る            | `assets:write`            |
| PUT    | `/v1/skills/:skillId/files`         | スキルのファイルを丸ごと入れ替える | `assets:write`            |
| PATCH  | `/v1/skills/:skillId/files`         | スキルの文書を書き換える      | `assets:write`            |
| PATCH  | `/v1/skills/:skillId`               | スキルの設定を変える        | `assets:write`            |
| DELETE | `/v1/skills/:skillId`               | スキルを消す            | `assets:delete`           |
| POST   | `/v1/skills/:skillId/copy`          | スキルを自分のスキルとしてコピー  | `assets:write`            |

### GET`/v1/skills`

自分が登録したスキルの一覧を取得します。最終更新日時の降順（新しい順）で返ります。カーソルベースのページネーションに対応しています。

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

| パラメータ         | 型         | デフォルト  | 説明                                                 |
| ------------- | --------- | ------ | -------------------------------------------------- |
| `active_only` | `boolean` | `true` | false を指定すると無効化したスキルも含めます。"true" / "false" 以外は 400 |
| `limit`       | `integer` | `50`   | 1 ページの取得件数（1-100）                                  |
| `cursor`      | `string`  | `—`    | 次ページ取得用カーソル（前回レスポンスの cursor 値）                     |

#### リクエスト例

**List skills**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?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）

| フィールド                         | 型                | 説明                                                                                                                                    |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `skills`                      | `array`          | スキルオブジェクトの配列                                                                                                                          |
| `skills[].skillId`            | `string`         | スキル ID（Chat の skillIds に指定します）                                                                                                        |
| `skills[].ownerUserId`        | `string \| null` | 持ち主の利用者 ID                                                                                                                            |
| `skills[].name`               | `string`         | スキル名                                                                                                                                  |
| `skills[].description`        | `string?`        | スキルの説明                                                                                                                                |
| `skills[].category`           | `string?`        | カテゴリ                                                                                                                                  |
| `skills[].tags`               | `array`          | タグの配列（同じタグは 1 つにして返します）。未設定の場合は空配列                                                                                                    |
| `skills[].isShared`           | `boolean`        | スキルを公開しているかどうか                                                                                                                        |
| `skills[].isActive`           | `boolean`        | 有効かどうか                                                                                                                                |
| `skills[].shareRequestStatus` | `string \| null` | 公開の申請の状態（「スキル・プレイブックの公開の承認」を参照）。同じく sharePendingVersionId・sharePendingListing・shareRequestNote・shareReviewNote・shareRequestedAt も入ります |
| `skills[].createdAt`          | `string`         | 作成日時（ISO 8601）                                                                                                                        |
| `skills[].updatedAt`          | `string`         | 最終更新日時（ISO 8601）                                                                                                                      |
| `hasMore`                     | `boolean`        | 次のページが存在するかどうか                                                                                                                        |
| `cursor`                      | `string`         | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                                                                 |

#### レスポンス例

```json
{
  "skills": [
    {
      "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "name": "release-notes",
      "description": "リリースノートを生成する",
      "category": "devops",
      "tags": ["ci"],
      "isShared": false,
      "isActive": true,
      "shareRequestStatus": null,
      "sharePendingVersionId": null,
      "shareRequestNote": null,
      "shareReviewNote": null,
      "shareRequestedAt": null,
      "sharePendingListing": null,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

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

`hasMore` が `true` の間、レスポンスの `cursor` をそのまま次のリクエストに渡してください。

```bash
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=50" \
  -H "Authorization: Bearer <access_token>"

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=50&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"
```

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

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

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

| ステータス | 説明                                     |
| ----- | -------------------------------------- |
| `400` | limit が 1-100 の整数でない                   |
| `400` | cursor が不正（前回レスポンスの値以外）                |
| `400` | active\_only が "true" / "false" 以外     |
| `403` | chat:exec / assets:read のいずれも持っていない    |
| `403` | システム連携のトークンで呼び出した（`code: "forbidden"`） |

### GET`/v1/skills/shared`

公開されているスキルの一覧を取得します（自分が公開したスキルも含まれます）。作成日時の降順（新しい順）で返ります。カーソルベースのページネーションに対応しています。

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

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

#### リクエスト例

**List shared skills**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared?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）

公開スキルは常に有効なため、`isShared` / `isActive` フィールドは含まれません。申請の状態の項目も含まれません。

| フィールド                  | 型                | 説明                                    |
| ---------------------- | ---------------- | ------------------------------------- |
| `skills`               | `array`          | スキルオブジェクトの配列                          |
| `skills[].skillId`     | `string`         | スキル ID（Chat の skillIds に指定します）        |
| `skills[].ownerUserId` | `string \| null` | 持ち主の利用者 ID                            |
| `skills[].name`        | `string`         | スキル名                                  |
| `skills[].description` | `string?`        | スキルの説明                                |
| `skills[].category`    | `string?`        | カテゴリ                                  |
| `skills[].tags`        | `array`          | タグの配列（同じタグは 1 つにして返します）。未設定の場合は空配列    |
| `skills[].createdAt`   | `string`         | 作成日時（ISO 8601）                        |
| `skills[].updatedAt`   | `string`         | 最終更新日時（ISO 8601）                      |
| `hasMore`              | `boolean`        | 次のページが存在するかどうか                        |
| `cursor`               | `string`         | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます |

#### レスポンス例

```json
{
  "skills": [
    {
      "skillId": "9c8b7a6d-5e4f-4a3b-8c1d-2e3f4a5b6c7d",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "name": "sql-review",
      "description": "SQL をレビューする",
      "category": null,
      "tags": [],
      "createdAt": "2026-07-20T00:00:00.000Z",
      "updatedAt": "2026-08-09T00:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                     |
| ----- | -------------------------------------- |
| `400` | limit が 1-100 の整数でない                   |
| `400` | cursor が不正（前回レスポンスの値以外）                |
| `403` | chat:exec / assets:read のいずれも持っていない    |
| `403` | システム連携のトークンで呼び出した（`code: "forbidden"`） |

### GET`/v1/skills/:skillId`

スキルを取得します。自分のスキルと、公開されているスキルを取得できます。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

#### リクエスト例

**Get skill**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
{
  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/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c", 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）

自分のスキルの一覧の 1 件と同じ項目に、次の 2 つを加えた形です。ほかの利用者の公開スキルでは、公開の一覧と同じく `isShared`・`isActive` と申請の状態の項目は含まれません。

| フィールド              | 型                | 説明                                                               |
| ------------------ | ---------------- | ---------------------------------------------------------------- |
| `currentVersionId` | `string \| null` | 今のバージョンの ID。バージョンの記録が始まる前に作られ、その後ファイルを変えていないスキルは null            |
| `digest`           | `string`         | スキルの設定を変えるときに baseDigest に送る値。公開・有効・カテゴリ・タグから作られ、ファイルを変えても変わりません |

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "リリースノートを生成する",
  "category": "devops",
  "tags": ["ci"],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "sharePendingVersionId": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "sharePendingListing": null,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
```

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

| ステータス | code                 | 説明                          |
| ----- | -------------------- | --------------------------- |
| `400` | `invalid_parameter`  | skillId が UUID の形式ではない      |
| `403` | `insufficient_scope` | assets:read スコープが不足         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した           |
| `404` | `skill_not_found`    | スキルが存在しない、またはほかの利用者の非公開のスキル |

### GET`/v1/skills/:skillId/versions`

スキルのバージョンの一覧を取得します。スキルのファイルを変えるたびに新しいバージョンができ、前のバージョンも残ります。新しいバージョンから順に、100 個まで返ります。ページネーションには対応していません（`hasMore` はいつも `false` で、100 個より古いバージョンがあっても返りません）。100 個より古いバージョンも、バージョンの ID が分かれば、ファイルの一覧を取得でき、バイナリでない文書と、200 KiB までの文書でない文字のファイルは 1 ファイルの取得で中身も読めます（すべてのファイルを読むには、そのバージョンを指定してスキルをコピーします）。

ほかの利用者の公開スキルでは、公開されていた間に公開されたバージョンだけを返します。承認待ち・差し戻しのバージョンや、公開していないうちのバージョンは返しません。管理者が公開を止めたスキルは、公開し直した後は、公開し直したときのバージョンとその後に公開されたバージョンだけを返します（止める前のバージョンは返しません）。返さないバージョンを指定すると `400 Bad Request`（`version_not_found`）です。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

#### リクエスト例

**List skill versions**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

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

| フィールド                        | 型                | 説明                                                                                                                                                |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skillId`                    | `string`         | スキル ID                                                                                                                                            |
| `currentVersionId`           | `string \| null` | 今のバージョンの ID                                                                                                                                       |
| `versions`                   | `array`          | バージョンの配列（新しい順）                                                                                                                                    |
| `versions[].versionId`       | `string \| null` | バージョンの ID                                                                                                                                         |
| `versions[].versionNo`       | `number`         | バージョンの番号（1 から）                                                                                                                                    |
| `versions[].parentVersionId` | `string \| null` | 元にしたバージョンの ID                                                                                                                                     |
| `versions[].source`          | `string`         | バージョンのでき方。"upload"（ファイルを送って作った・入れ替えた）、"edit"（文書を書き換えた）、"copy"（コピーで作った）、"baseline"（バージョンの記録が始まる前からの内容）、"listing"（公開中のスキルのカテゴリ・タグの変更を承認待ちにするために作った） |
| `versions[].contentDigest`   | `string \| null` | バージョンのファイルの中身から作った値。同じ中身のバージョンは同じ値になります                                                                                                           |
| `versions[].createdAt`       | `string`         | バージョンができた日時（ISO 8601）                                                                                                                             |
| `versions[].isCurrent`       | `boolean`        | 今のバージョンかどうか                                                                                                                                       |
| `hasMore`                    | `boolean`        | いつも false                                                                                                                                         |

バージョンの記録が始まる前に作られ、その後ファイルを変えていないスキルは、`versionId`・`contentDigest` が `null`、`source` が `"baseline"` の 1 件を返します。

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "versions": [
    {
      "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
      "versionNo": 2,
      "parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
      "source": "edit",
      "contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
      "createdAt": "2026-08-05T09:00:00.000Z",
      "isCurrent": true
    },
    {
      "versionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
      "versionNo": 1,
      "parentVersionId": null,
      "source": "upload",
      "contentDigest": "3cd01ce0220c4f7a9b1d3e5f70a2c4e6b8d0f1a3c5e7b9d1f3a5c7e9b0d2f4a6",
      "createdAt": "2026-08-01T03:12:45.123Z",
      "isCurrent": false
    }
  ],
  "hasMore": false
}
```

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

| ステータス | code                 | 説明                          |
| ----- | -------------------- | --------------------------- |
| `400` | `invalid_parameter`  | skillId が UUID の形式ではない      |
| `403` | `insufficient_scope` | assets:read スコープが不足         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した           |
| `404` | `skill_not_found`    | スキルが存在しない、またはほかの利用者の非公開のスキル |

### GET`/v1/skills/:skillId/files`

スキルのバージョンのファイルの一覧を取得します。ファイルの中身は返しません（1 ファイルの取得で読みます）。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| パラメータ        | 型        | デフォルト   | 説明                                                                                           |
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------- |
| `version_id` | `string` | 今のバージョン | 読むバージョンの ID（UUID）。前の名前 versionId でも受け付けます。省いたとき、持ち主が読み、公開の承認待ち・差し戻しのバージョンがあるときは、そのバージョンを読みます |

#### リクエスト例

**List skill files**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
{
  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/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", 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）

| フィールド              | 型                | 説明                                                                                                                                                                       |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `skillId`          | `string`         | スキル ID                                                                                                                                                                   |
| `versionId`        | `string \| null` | バージョンの ID                                                                                                                                                                |
| `isCurrent`        | `boolean`        | 今のバージョンかどうか                                                                                                                                                              |
| `digest`           | `string`         | スキルのファイルを丸ごと入れ替える・スキルの文書を書き換えるときに baseDigest に送る値（version\_id を省いて読んだ一覧の値を送ります）                                                                                          |
| `editable`         | `boolean`        | 文書を書き換えられるかどうか。自分のスキルで、スクリプトや実行ファイル（.exe・.bin・.so・.dylib・.dll）を含まないときに true                                                                                              |
| `files`            | `array`          | ファイルの配列（パスの順）                                                                                                                                                            |
| `files[].path`     | `string`         | スキルの中のパス（例: scripts/run.py）                                                                                                                                              |
| `files[].kind`     | `string`         | ファイルの種類（拡張子で決まります）。"document"（.md・.json・.yaml・.yml）、"script"（.py・.js・.mjs・.cjs・.ts・.sh・.bash・.zsh・.rb・.pl・.php・.go・.rs・.java・.ps1・.bat・.cmd）、"other"（それ以外。設定値のファイル・画像など） |
| `files[].size`     | `number`         | 大きさ（バイト）                                                                                                                                                                 |
| `files[].editable` | `boolean`        | 文書を書き換えるで中身を変えられる形式かどうか（文書で、バイナリでないときに true）                                                                                                                             |
| `hasMore`          | `boolean`        | いつも false（全件を返します）                                                                                                                                                       |

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "isCurrent": true,
  "digest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
  "editable": true,
  "files": [
    { "path": "SKILL.md", "kind": "document", "size": 1834, "editable": true },
    { "path": "templates/notes.md", "kind": "document", "size": 412, "editable": true }
  ],
  "hasMore": false
}
```

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

| ステータス | code                 | 説明                                                                           |
| ----- | -------------------- | ---------------------------------------------------------------------------- |
| `400` | `invalid_parameter`  | skillId または version\_id が UUID の形式ではない、または version\_id と versionId に違う値を指定した |
| `400` | `version_not_found`  | version\_id が、そのスキルのバージョンではない                                                |
| `403` | `insufficient_scope` | assets:read スコープが不足                                                          |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                                            |
| `404` | `skill_not_found`    | スキルが存在しない、またはほかの利用者の非公開のスキル                                                  |

### GET`/v1/skills/:skillId/files/content`

スキルの 1 ファイルの中身を取得します。中身はいつも全文で返ります。

前のバージョンで中身を読めるのは、文書（`kind` が `"document"` で、バイナリでないもの。大きさを問わず全文）と、200 KiB までの文字のファイルです。持ち主で、公開の承認待ち・差し戻しのバージョンがあるときは、公開中のバージョンも同じです（バージョンを省くと、承認待ち・差し戻しのバージョンのすべてのファイルを読めます）。これらのバージョンの、バイナリのファイル（文書を含む）と、200 KiB を超える文書でないファイルは `400`（`version_not_readable`）になります。前のバージョンのすべてのファイルを読むには、スキルのコピー（`POST /v1/skills/:skillId/copy`）で `versionId` を指定してコピーし、コピーしたスキルをダウンロード（`GET /v1/skills/:skillId/download`）してください。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| パラメータ        | 型        | デフォルト   | 説明                                                                                           |
| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------- |
| `path`       | `string` | —       | 必須。ファイルのパス（ファイルの一覧の files\[].path。例: scripts/run.py）                                         |
| `version_id` | `string` | 今のバージョン | 読むバージョンの ID（UUID）。前の名前 versionId でも受け付けます。省いたとき、持ち主が読み、公開の承認待ち・差し戻しのバージョンがあるときは、そのバージョンを読みます |

#### リクエスト例

**Get skill file**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content",
  headers={"Authorization": f"Bearer {token}"},
  params={"path": "SKILL.md"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content" + "?path=SKILL.md",
{
  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/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md", 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）

| フィールド       | 型                | 説明                                                    |
| ----------- | ---------------- | ----------------------------------------------------- |
| `skillId`   | `string`         | スキル ID                                                |
| `versionId` | `string \| null` | バージョンの ID                                             |
| `path`      | `string`         | ファイルのパス                                               |
| `kind`      | `string`         | ファイルの種類（ファイルの一覧の files\[].kind と同じ）                   |
| `size`      | `number`         | 大きさ（バイト）                                              |
| `encoding`  | `string`         | 中身の表し方。文字のファイルは "utf-8"、バイナリ（中身に NUL を含むもの）は "base64" |
| `content`   | `string`         | ファイルの中身（全文）                                           |

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "path": "SKILL.md",
  "kind": "document",
  "size": 88,
  "encoding": "utf-8",
  "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"
}
```

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

| ステータス | code                   | 説明                                                                                               |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| `400` | `invalid_parameter`    | skillId または version\_id が UUID の形式ではない、version\_id と versionId に違う値を指定した、または path が無い            |
| `400` | `file_not_found`       | path のファイルが、そのバージョンに無い                                                                           |
| `400` | `version_not_found`    | version\_id が、そのスキルのバージョンではない                                                                    |
| `400` | `version_not_readable` | 前のバージョン（持ち主で、公開の承認待ち・差し戻しのバージョンがあるときは公開中のバージョンも）の、バイナリのファイル（文書を含む）または 200 KiB を超える文書でないファイルを指定した |
| `403` | `insufficient_scope`   | assets:read スコープが不足                                                                              |
| `403` | `forbidden`            | システム連携のトークンで呼び出した                                                                                |
| `404` | `skill_not_found`      | スキルが存在しない、またはほかの利用者の非公開のスキル                                                                      |

### GET`/v1/skills/:skillId/download`

スキルの今のバージョン（持ち主がダウンロードし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン）のすべてのファイル（設定値のファイル・画像なども）を、zip で取得します。バージョンは指定できません。

- レスポンスの `Content-Type` は `application/zip` です。ファイル名（`Content-Disposition`）は、スキルの名前をもとにしたもの（拡張子は `.zip`）です。
- zip の中にトップフォルダはありません。そのままスキルを作る（`POST /v1/skills`）・ファイルを丸ごと入れ替える（`PUT /v1/skills/:skillId/files`）に送れます。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| ステータス | code                 | 説明                          |
| ----- | -------------------- | --------------------------- |
| `400` | `invalid_parameter`  | skillId が UUID の形式ではない      |
| `403` | `insufficient_scope` | assets:read スコープが不足         |
| `403` | `forbidden`          | システム連携のトークンで呼び出した           |
| `404` | `skill_not_found`    | スキルが存在しない、またはほかの利用者の非公開のスキル |

#### リクエスト例

**Download skill**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download",
{
  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/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download", 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)
```

### POST`/v1/skills`

スキルを作ります。リクエストは `multipart/form-data` で送ります。名前と説明は、`SKILL.md` の先頭の YAML（`---` で囲んだ部分）の `name`・`description` から読みます。

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

| フィールド              | 型        | 必須 | 説明                                                                                                                                                |
| ------------------ | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `files`            | `file`   | 必須 | スキルのファイル。zip 1 つ、または SKILL.md を含むファイル群を送ります。ファイル群は 1 項目に 1 ファイルで、ファイル名をスキルの中のパス（例: scripts/run.py）にします。拡張子が .md のファイル 1 つだけを送ると、SKILL.md として保存します |
| `category`         | `string` | —  | カテゴリ（前後の空白を除いて 40 文字まで）                                                                                                                           |
| `tags`             | `string` | —  | タグ。1 項目に 1 つで、項目を繰り返して送ります（前後の空白と先頭の # を除いて 1〜24 文字のものを 10 個まで）。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません                                           |
| `isShared`         | `string` | —  | 公開するかどうか（"true" または "false"）。省くと非公開                                                                                                               |
| `isActive`         | `string` | —  | 有効かどうか（"true" または "false"）。省くと有効。公開するスキルは有効にしてください                                                                                                |
| `shareRequestNote` | `string` | —  | 公開の申請の理由（前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照）                                                                                               |

スキルのファイルの決まり:

- ルートに `SKILL.md` が要ります。`SKILL.md` の先頭の YAML に `name`（100 文字まで）が要ります。`description` は省けます（1024 文字を超える分は、一覧などに出る説明では切って保存します。`SKILL.md` はそのまま残ります）。
- zip の中が 1 つのフォルダにまとまっているときは、そのフォルダを外して保存します。OS が作るファイル（`__MACOSX/`・`._` で始まるもの・`.DS_Store`・`Thumbs.db`・`desktop.ini`）は保存しません。
- ファイルは 1〜50 個、1 ファイル 2 MiB まで、展開した後の合計 5 MiB までです。
- 送るファイルの大きさの合計（ファイル群をまとめた後の大きさを含みます）は 6 MiB 未満にしてください。
- 中身は安全の検査を通します。

#### リクエスト例

**Create skill**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills \
-H "Authorization: Bearer <access_token>" \
-F "files=@SKILL.md" \
-F "category=devops" \
-F "tags=ci"
```

**Python**

```python
import requests

with open("SKILL.md", "rb") as f:
  response = requests.post(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={"category": "devops", "tags": "ci"},
  )

print(response.json())
```

**TypeScript**

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

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

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

**Go**

```go
file, _ := os.Open("SKILL.md")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "SKILL.md")
io.Copy(part, file)
writer.WriteField("category", "devops")
writer.WriteField("tags", "ci")
writer.Close()

req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### レスポンス（201 Created）

自分のスキルの取得と同じ形で、作ったスキルを返します。

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "リリースノートを生成する",
  "category": "devops",
  "tags": [
    "ci"
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "sharePendingVersionId": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "sharePendingListing": null,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
```

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

| ステータス | code                     | 説明                                                                                                         |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | files が無い、同じパスのファイルを 2 つ送った、files 以外の項目でファイルを送った、フォームの項目が多すぎる・長すぎる、または category・tags・isShared・isActive の誤り |
| `400` | `file_count`             | ファイルが 0 個（空の zip など）、または 50 個を超える                                                                          |
| `400` | `file_too_large`         | 1 ファイルが 2 MiB を超える                                                                                         |
| `400` | `total_too_large`        | 展開した後の合計が 5 MiB を超える                                                                                       |
| `400` | `zip_invalid`            | zip を展開できない                                                                                                |
| `400` | `bad_path`               | ファイルのパスが不正（.. を含む など）                                                                                      |
| `400` | `skill_md_missing`       | ルートに SKILL.md が無い                                                                                          |
| `400` | `frontmatter_missing`    | SKILL.md の先頭に YAML（--- で囲んだ部分）が無い                                                                          |
| `400` | `name_missing`           | SKILL.md の YAML に name が無い                                                                                 |
| `400` | `name_too_long`          | SKILL.md の name が 100 文字を超える                                                                               |
| `400` | `shared_requires_active` | 無効のまま公開しようとした                                                                                              |
| `400` | `guardrail_blocked`      | 中身が安全の検査で止められた                                                                                             |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                                                       |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                          |
| `413` | `body_too_large`         | 送ったファイルの大きさの合計が上限を超える                                                                                      |
| `415` | `unsupported_media_type` | Content-Type が multipart/form-data ではない                                                                    |
| `502` | `blob_write_failed`      | ファイルを保存できなかった（送り直してください）                                                                                   |
| `503` | `guardrail_unavailable`  | 安全の検査を使えない（時間をおいて送り直してください）                                                                                |

```bash
curl -X POST "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills" \
  -H "Authorization: Bearer <access_token>" \
  -F "files=@SKILL.md;filename=SKILL.md" \
  -F "files=@scripts/run.py;filename=scripts/run.py" \
  -F "category=devops" \
  -F "tags=ci" \
  -F "tags=release"
```

### PUT`/v1/skills/:skillId/files`

自分のスキルのファイルを、送ったファイルで丸ごと入れ替えます。新しいバージョンができ、前のバージョンは残ります。送らなかったファイルは新しいバージョンに入りません。リクエストは `multipart/form-data` で送ります。

- 名前と説明は、新しい `SKILL.md` から読み直します。
- バージョンを固定せずにこのスキルを使っている Agent とスケジュールは、新しいバージョンを使うようになります（バージョンを固定したものは変わりません）。公開の承認が有効なテナントで公開中のスキルは、新しいバージョンが承認されるまで前のバージョンのままです。
- 送り直すと、1 回目でバージョンが変わっているため `409 Conflict`（`stale_base`）が返ります。ファイルの一覧を取得し直して、変わったかを確かめてください。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| フィールド              | 型        | 必須 | 説明                                                  |
| ------------------ | -------- | -- | --------------------------------------------------- |
| `baseDigest`       | `string` | 必須 | ファイルの一覧（version\_id を省いて読んだもの）の digest              |
| `files`            | `file`   | 必須 | スキルのファイル。送り方と決まりはスキルを作るときと同じです                      |
| `shareRequestNote` | `string` | —  | 公開の申請の理由（前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照） |

カテゴリ・タグ・公開・有効は受け付けません（送っても読みません）。スキルの設定を変える（`PATCH /v1/skills/:skillId`）で変えてください。

公開の承認が有効なテナントで、承認待ちのスキルの中身を変えると、承認待ちのまま、変えた後の内容で承認を待ちます。管理者が公開の承認をやめた後に、承認待ちのスキルの中身を変えると、その変更で公開されます。画面で変えた場合と同じです（[公開の承認](#assets-share-approval)）。

`baseDigest` の確認は、変えてよい利用者かの確認より先に行います。このため、ほかの利用者の公開スキルでは、`baseDigest` が合わなければ `409 Conflict`、合えば `404 Not Found` が返ります。

#### リクエスト例

**Replace skill files**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
-H "Authorization: Bearer <access_token>" \
-F "files=@SKILL.md" \
-F "baseDigest=WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"
```

**Python**

```python
import requests

with open("SKILL.md", "rb") as f:
  response = requests.put(
      "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
      headers={"Authorization": f"Bearer {token}"},
      files={"files": f},
      data={"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"},
  )

print(response.json())
```

**TypeScript**

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

const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", {
method: "PUT",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});

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

**Go**

```go
file, _ := os.Open("SKILL.md")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "SKILL.md")
io.Copy(part, file)
writer.WriteField("baseDigest", "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0")
writer.Close()

req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

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

自分のスキルの取得と同じ形で、入れ替えた後のスキル（新しい `currentVersionId`）を返します。公開の承認が有効なテナントで公開中のスキルは、`currentVersionId` は変わらず、新しいバージョンの ID が `sharePendingVersionId` に入ります。新しいバージョンのファイルの一覧の `digest` は、ファイルの一覧で取得してください。

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "リリースノートを生成する",
  "category": "devops",
  "tags": [
    "ci"
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "sharePendingVersionId": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "sharePendingListing": null,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-06T10:00:00.000Z",
  "currentVersionId": "8c2e4a6b-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
  "digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
```

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

| ステータス | code                     | 説明                                                                                                   |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | skillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、files が無い、同じパスのファイルを 2 つ送った、または files 以外の項目でファイルを送った |
| `400` | `file_count`             | ファイルが 0 個（空の zip など）、または 50 個を超える                                                                    |
| `400` | `file_too_large`         | 1 ファイルが 2 MiB を超える                                                                                   |
| `400` | `total_too_large`        | 展開した後の合計が 5 MiB を超える                                                                                 |
| `400` | `zip_invalid`            | zip を展開できない                                                                                          |
| `400` | `bad_path`               | ファイルのパスが不正（.. を含む など）                                                                                |
| `400` | `skill_md_missing`       | ルートに SKILL.md が無い                                                                                    |
| `400` | `frontmatter_missing`    | SKILL.md の先頭に YAML（--- で囲んだ部分）が無い                                                                    |
| `400` | `name_missing`           | SKILL.md の YAML に name が無い                                                                           |
| `400` | `name_too_long`          | SKILL.md の name が 100 文字を超える                                                                         |
| `400` | `guardrail_blocked`      | 中身が安全の検査で止められた                                                                                       |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                                                 |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                                    |
| `404` | `skill_not_found`        | スキルが存在しない、またはほかの利用者のスキル                                                                              |
| `409` | `stale_base`             | ファイルの一覧を取得した後に、スキルのファイルが変わっている                                                                       |
| `413` | `body_too_large`         | 送ったファイルの大きさの合計が上限を超える                                                                                |
| `415` | `unsupported_media_type` | Content-Type が multipart/form-data ではない                                                              |
| `502` | `blob_write_failed`      | ファイルを保存できなかった                                                                                        |
| `503` | `guardrail_unavailable`  | 安全の検査を使えない（時間をおいて送り直してください）                                                                          |

### PATCH`/v1/skills/:skillId/files`

自分のスキルの文書（`.md`・`.json`・`.yaml`・`.yml`）を書き換えます。送った文書だけを変えた新しいバージョンができ、送らなかったファイルは今のバージョン（公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン）から引き継ぎます。前のバージョンは残ります。

- 文書を足す・書き換える・消すことができます。文書でないファイルは変えられません。スクリプトや実行ファイルを含むスキルは書き換えられません（ファイルを丸ごと入れ替える `PUT /v1/skills/:skillId/files` で直してください）。
- `SKILL.md` は消せません。`SKILL.md` を書き換えると、名前と説明も読み直します。
- JSON・YAML の文書は構文を確かめます。書き換えた後のスキルも、ファイル 50 個・1 ファイル 2 MiB・合計 5 MiB までです。書き換えた文書は安全の検査を通します。
- バージョンを固定せずにこのスキルを使っている Agent とスケジュールは、新しいバージョンを使うようになります（バージョンを固定したものは変わりません）。公開の承認が有効なテナントで公開中のスキルは、新しいバージョンが承認されるまで前のバージョンのままです。
- 公開の申請の理由（`shareRequestNote`）は送れません（送ると `400 Bad Request`（`invalid_parameter`））。理由を付けるときは、ファイルを丸ごと入れ替える（`PUT /v1/skills/:skillId/files`）で送ってください。公開の承認が有効なテナントで、公開中のスキルの承認待ちのバージョンをこの API で直しても、申請の理由はそのまま残ります。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| ヘッダー              | 必須 | 説明                                                                                |
| ----------------- | -- | --------------------------------------------------------------------------------- |
| `Idempotency-Key` | —  | 送り直しを見分けるキー（英数字と \_ . : - の 8〜128 文字）。同じキーで送り直すと、新しいバージョンを作らずに、1 回目にできたバージョンを返します |

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

| フィールド               | 型         | 必須 | 説明                                                      |
| ------------------- | --------- | -- | ------------------------------------------------------- |
| `baseDigest`        | `string`  | 必須 | ファイルの一覧（version\_id を省いて読んだもの）の digest                  |
| `changes`           | `array`   | 必須 | 変える文書（1〜50 件。同じパスは 1 回だけ）                               |
| `changes[].path`    | `string`  | 必須 | 文書のパス（例: SKILL.md、templates/notes.md）。無いパスを指定すると文書を足します |
| `changes[].content` | `string`  | —  | 文書の新しい中身（全文）。消すときは省きます                                  |
| `changes[].deleted` | `boolean` | —  | true で文書を消します（true または false。ほかの値は送れません）                |

```json
{
  "baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
  "changes": [
    { "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n..." },
    { "path": "templates/old.md", "deleted": true }
  ]
}
```

#### リクエスト例

**Edit skill files**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: edit-skill-20261118-0001" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
  "changes": [
    {
      "path": "SKILL.md",
      "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"
    },
    {
      "path": "templates/old.md",
      "deleted": true
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "edit-skill-20261118-0001"},
  json={'baseDigest': 'WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0', 'changes': [{'path': 'SKILL.md', 'content': '---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n'}, {'path': 'templates/old.md', 'deleted': True}]},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "edit-skill-20261118-0001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0", "changes": [{"path": "SKILL.md", "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"}, {"path": "templates/old.md", "deleted": true}]}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0", "changes": [{"path": "SKILL.md", "content": "---\nname: release-notes\ndescription: リリースノートを生成する\n---\n\n# 手順\n"}, {"path": "templates/old.md", "deleted": true}]}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "edit-skill-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### レスポンス（201 Created）

| フィールド     | 型        | 説明                                                                   |
| --------- | -------- | -------------------------------------------------------------------- |
| `skill`   | `object` | 書き換えた後のスキル（自分のスキルの取得と同じ形。ただし sharePendingListing は入りません。スキルの取得で読めます） |
| `version` | `object` | できたバージョン（バージョンの一覧の versions\[] の 1 件と同じ形）                            |

同じ `Idempotency-Key` で送り直したときは、`200 OK` で、1 回目にできたバージョン（`version`）と今のスキル（`skill`）を返します。同じキーで中身の違う書き換えを送ると `409 Conflict`（`command_conflict`）が返ります。1 回目の処理が終わる前に送り直すと `409 Conflict`（`stale_base`）が返ることがあります。終わってから同じキーで送り直してください。

#### レスポンス例

```json
{
  "skill": {
    "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
    "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
    "name": "release-notes",
    "description": "リリースノートを生成する",
    "category": "devops",
    "tags": [
      "ci"
    ],
    "isShared": false,
    "isActive": true,
    "shareRequestStatus": null,
    "sharePendingVersionId": null,
    "shareRequestNote": null,
    "shareReviewNote": null,
    "shareRequestedAt": null,
    "createdAt": "2026-08-01T03:12:45.123Z",
    "updatedAt": "2026-08-05T09:00:00.000Z",
    "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
    "digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
  },
  "version": {
    "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
    "versionNo": 2,
    "parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
    "source": "edit",
    "contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
    "createdAt": "2026-08-05T09:00:00.000Z",
    "isCurrent": true
  }
}
```

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

| ステータス | code                      | 説明                                                                                                             |
| ----- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`       | skillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、changes\[].deleted が true・false ではない、または shareRequestNote を送った |
| `400` | `idempotency_key_invalid` | Idempotency-Key の形式が誤っている                                                                                      |
| `400` | `invalid_body`            | ボディが壊れた JSON、または JSON のオブジェクトではない                                                                              |
| `400` | `no_changes`              | changes が無い、空、または 50 件を超える                                                                                     |
| `400` | `bad_change`              | changes の 1 件の形の誤り（path が無い、content が文字列でない など）、または同じパスを 2 回指定した                                               |
| `400` | `bad_path`                | path が不正（.. を含む など）                                                                                            |
| `400` | `not_editable`            | 文書でないファイルを指定した                                                                                                 |
| `400` | `code_skill_not_editable` | スクリプトや実行ファイルを含むスキル                                                                                             |
| `400` | `skill_md_required`       | SKILL.md を消そうとした                                                                                               |
| `400` | `file_too_large`          | 1 ファイルが 2 MiB を超える                                                                                             |
| `400` | `invalid_syntax`          | JSON・YAML の文書の構文の誤り                                                                                            |
| `400` | `skill_too_large`         | 書き換えた後のスキルが 50 ファイルまたは合計 5 MiB を超える                                                                            |
| `400` | `frontmatter_missing`     | SKILL.md の先頭に YAML（--- で囲んだ部分）が無い                                                                              |
| `400` | `name_missing`            | SKILL.md の YAML に name が無い                                                                                     |
| `400` | `name_too_long`           | SKILL.md の name が 100 文字を超える                                                                                   |
| `400` | `guardrail_blocked`       | 中身が安全の検査で止められた                                                                                                 |
| `403` | `insufficient_scope`      | assets:write スコープが不足                                                                                           |
| `403` | `forbidden`               | システム連携のトークンで呼び出した                                                                                              |
| `404` | `skill_not_found`         | スキルが存在しない、またはほかの利用者のスキル                                                                                        |
| `409` | `stale_base`              | ファイルの一覧を取得した後に、スキルのファイルが変わっている（読めない baseDigest も含みます）                                                          |
| `409` | `command_conflict`        | 同じ Idempotency-Key で、中身の違う書き換えを送った                                                                             |
| `413` | `body_too_large`          | ボディが 3 MiB を超える                                                                                                |
| `415` | `unsupported_media_type`  | ボディの Content-Type が application/json ではない                                                                      |
| `502` | `blob_write_failed`       | ファイルを保存できなかった                                                                                                  |
| `503` | `guardrail_unavailable`   | 安全の検査を使えない（時間をおいて送り直してください）                                                                                    |

### PATCH`/v1/skills/:skillId`

自分のスキルの設定（公開・有効・カテゴリ・タグ）を変えます。送った項目だけを変えます。名前と説明は `SKILL.md` から読むので、ここでは変えられません。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| フィールド              | 型                | 必須 | 説明                                                                                                                                                                                 |
| ------------------ | ---------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`       | `string`         | 必須 | スキルの取得の digest                                                                                                                                                                     |
| `isShared`         | `boolean`        | —  | 公開するかどうか。公開の承認が有効なテナントでは、true で承認待ちになり、承認待ちのものに false を送ると申請を取り下げます                                                                                                                |
| `isActive`         | `boolean`        | —  | 有効かどうか                                                                                                                                                                             |
| `category`         | `string \| null` | —  | カテゴリ（前後の空白を除いて 40 文字まで）。null か空の文字列で空にします。公開の承認が有効なテナントで公開中のスキルは、同じ更新で isShared: false を送らない限り、承認待ちになります（「スキル・プレイブックの公開の承認」を参照）                                                    |
| `tags`             | `array`          | —  | タグ（前後の空白と先頭の # を除いて 1〜24 文字の文字列を 10 個まで）。空にするときは \[]。小文字にし、先頭の # を除いて保存します。そうして同じになるタグは送れません。公開の承認が有効なテナントで公開中のスキルは、同じ更新で isShared: false を送らない限り、承認待ちになります（「スキル・プレイブックの公開の承認」を参照） |
| `shareRequestNote` | `string \| null` | —  | 公開の申請の理由（前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照）                                                                                                                                |

baseDigest のほかに、少なくとも 1 つの項目（shareRequestNote を除きます）を送ってください。公開の申請の理由（`shareRequestNote`。[公開の承認](#assets-share-approval)）も送れます。変えた後に「公開していて無効」になる変更は `400`（`shared_requires_active`）です。

`baseDigest` の確認は、変えてよい利用者かの確認より先に行います。このため、ほかの利用者の公開スキルでは、`baseDigest` が合わなければ `409 Conflict`、合えば `404 Not Found` が返ります。

#### リクエスト例

**Update skill**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro",
  "category": "release"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': '8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro', 'category': 'release'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro", "category": "release"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro", "category": "release"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c", 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)
```

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

自分のスキルの取得と同じ形で、変えた後のスキル（そのときの `digest`）を返します。公開の承認が有効なテナントで公開中のスキルのカテゴリ・タグを変えたとき（同じ更新で `isShared: false` を送らないとき）は、`category`・`tags` は前の値のままで、変えた値は `sharePendingListing` に入ります（`shareRequestStatus` は `"pending"`）。カテゴリ・タグの変更だけでは `digest` は変わりません。

#### レスポンス例

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "リリースノートを生成する",
  "category": "release",
  "tags": [
    "ci"
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "sharePendingVersionId": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "sharePendingListing": null,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "digest": "ZEs4wUG1R0Xfjmy6jVkkMLsikpWmXBZKAziwGO0gj9k"
}
```

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

| ステータス | code                     | 説明                                                                       |
| ----- | ------------------------ | ------------------------------------------------------------------------ |
| `400` | `invalid_parameter`      | skillId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、または項目の型や長さ・数の誤り |
| `400` | `shared_requires_active` | 変えた後に、公開していて無効になる                                                        |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                        |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                     |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                        |
| `404` | `skill_not_found`        | スキルが存在しない、またはほかの利用者のスキル                                                  |
| `409` | `stale_base`             | 取得した後にスキルの設定が変わっている                                                      |
| `413` | `body_too_large`         | ボディが 3 MiB を超える                                                          |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                |

### DELETE`/v1/skills/:skillId`

自分のスキルを、すべてのバージョンのファイルとともに消します。システム管理者は、ほかの利用者が公開したスキルも消せます。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明           |
| --------- | -------- | -- | ------------ |
| `skillId` | `string` | 必須 | スキル ID（UUID） |

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

| パラメータ   | 型        | デフォルト     | 説明                                                                        |
| ------- | -------- | --------- | ------------------------------------------------------------------------- |
| `force` | `string` | `"false"` | "true" を指定すると、このスキルを使っているスケジュールや Agent があっても消します。"true" / "false" 以外は 400 |

- **使っているとき**: このスキルを使うスケジュールか、このスキルを定義に持つ Agent があると、`409 Conflict`（`skill_referenced`。使っているスケジュールと Agent の数は `error.message`）が返ります。スケジュールは、すべての利用者のものを、有効・無効を問わず数えます。Agent は持ち主を問わず数えます。プロジェクトのジョブ（プロジェクトに置いた Agent の巡回と、まだ動き始めていないプロジェクトの実行）は、スケジュールとしては数えません。
- **`force=true` のとき**: 使っているスケジュールからこのスキルを外し（ほかの利用者のスケジュールからも外します。スケジュールそのものは残ります）、このスキルを定義に持つ全員の Agent から外してから、スキルを消します。外した Agent の巡回は、外した後の定義で動き続けます。

#### リクエスト例

**Delete skill**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  headers={"Authorization": f"Bearer {token}"},
  params={"force": "false"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c" + "?force=false",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

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

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "deleted": true
}
```

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

| ステータス | code                 | 説明                                                     |
| ----- | -------------------- | ------------------------------------------------------ |
| `400` | `invalid_parameter`  | skillId が UUID の形式ではない、または force が "true" / "false" 以外 |
| `403` | `insufficient_scope` | assets:delete スコープが不足                                  |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                                      |
| `404` | `skill_not_found`    | スキルが存在しない、またはほかの利用者のスキルで消せない                           |
| `409` | `skill_referenced`   | スケジュールか Agent が使っている（force=true で消せます）                 |

### POST`/v1/skills/:skillId/copy`

自分のスキルか公開されているスキルを、自分の新しいスキルとしてコピーします。指定したバージョン（省くと今のバージョン。持ち主がコピーし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン）のすべてのファイルを写し、非公開・有効で作ります。名前・説明・カテゴリ・タグは、コピー元の今のものを写します。コピーしたスキルのバージョンは 1 から始まります。

ボディは省けます。バージョンを指定するときは JSON で送ります。

#### パスパラメータ

| パラメータ     | 型        | 必須 | 説明                 |
| --------- | -------- | -- | ------------------ |
| `skillId` | `string` | 必須 | コピーするスキルの ID（UUID） |

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

| ヘッダー              | 必須 | 説明                                                                     |
| ----------------- | -- | ---------------------------------------------------------------------- |
| `Idempotency-Key` | —  | 送り直しを見分けるキー（英数字と \_ . : - の 8〜128 文字）。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します |

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

| フィールド       | 型        | 必須 | 説明                                                                     |
| ----------- | -------- | -- | ---------------------------------------------------------------------- |
| `versionId` | `string` | —  | 写すバージョンの ID（UUID）。省くと今のバージョン（持ち主がコピーし、公開の承認待ち・差し戻しのバージョンがあるときはそのバージョン） |

#### リクエスト例

**Copy skill**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: copy-skill-20261118-0001" \
-H "Content-Type: application/json" \
-d '{
  "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-skill-20261118-0001"},
  json={'versionId': '5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "copy-skill-20261118-0001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"}),
}
);

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

**Go**

```go
payload := []byte(`{"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-skill-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### レスポンス（201 Created）

自分のスキルの取得と同じ形で、コピーして作ったスキルを返します。

同じ `Idempotency-Key` で送り直したときは、`200 OK` で、1 回目のコピー（今の内容）を同じ形で返します。送り直しで `versionId` を省くと、1 回目にどのバージョンを写したかによらず 1 回目のコピーが返ります。1 回目のコピーが消されていると `404 Not Found`（`skill_not_found`）が返ります。新しいキーで送ってください。

#### レスポンス例

```json
{
  "skillId": "9e1f3a5b-7c2d-4e6f-8a0b-1c3d5e7f9a2b",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "リリースノートを生成する",
  "category": "devops",
  "tags": [
    "ci"
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "sharePendingVersionId": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "sharePendingListing": null,
  "createdAt": "2026-11-18T05:00:00.000Z",
  "updatedAt": "2026-11-18T05:00:00.000Z",
  "currentVersionId": "d7e9f1a3-5b2c-4d6e-8f0a-2c4e6a8b0d1f",
  "digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
```

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

| ステータス | code                      | 説明                                                                           |
| ----- | ------------------------- | ---------------------------------------------------------------------------- |
| `400` | `invalid_parameter`       | skillId または versionId が UUID の形式ではない                                         |
| `400` | `idempotency_key_invalid` | Idempotency-Key の形式が誤っている                                                    |
| `400` | `version_not_found`       | versionId が、そのスキルのバージョンではない                                                  |
| `400` | `invalid_body`            | ボディが壊れた JSON、または JSON のオブジェクトではない                                            |
| `403` | `insufficient_scope`      | assets:write スコープが不足                                                         |
| `403` | `forbidden`               | システム連携のトークンで呼び出した                                                            |
| `404` | `skill_not_found`         | スキルが存在しない、ほかの利用者の非公開のスキル、または同じ Idempotency-Key で作ったコピーが消されている（新しいキーで送ってください） |
| `409` | `idempotency_conflict`    | 同じ Idempotency-Key で、別のスキルのコピー、または 1 回目と違う versionId のコピーを送った                |
| `413` | `body_too_large`          | ボディが 3 MiB を超える                                                              |
| `415` | `unsupported_media_type`  | ボディの Content-Type が application/json ではない                                    |
| `502` | `blob_write_failed`       | ファイルを保存できなかった                                                                |

## プレイブック

プレイブックを読む・作る・変える・消す・コピーします。`playbookId` は、Chat の `playbookId` パラメータに指定して決まった手順でエージェントを実行させるときや、Agent の定義（`spec.playbookId`）に使います。共通の決まりは [Agent・Playbook・Skill の共通の決まり](#assets-common) を参照してください。

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

| メソッド   | エンドポイント                          | 説明                            | スコープ (SaaS)               |
| ------ | -------------------------------- | ----------------------------- | ------------------------- |
| GET    | `/v1/playbooks`                  | 自分のプレイブック一覧を取得                | `chat:exec / assets:read` |
| GET    | `/v1/playbooks/shared`           | 公開されているプレイブック一覧を取得            | `chat:exec / assets:read` |
| GET    | `/v1/playbooks/:playbookId`      | プレイブックを取得                     | `assets:read`             |
| POST   | `/v1/playbooks`                  | プレイブックを作る                     | `assets:write`            |
| PATCH  | `/v1/playbooks/:playbookId`      | プレイブックを変える                    | `assets:write`            |
| DELETE | `/v1/playbooks/:playbookId`      | プレイブックを消す                     | `assets:delete`           |
| POST   | `/v1/playbooks/:playbookId/copy` | 公開されているプレイブックを自分のプレイブックとしてコピー | `assets:write`            |

### GET`/v1/playbooks`

プレイブックの一覧を取得します。利用回数の多い順（同数の場合は作成日時の新しい順）で返ります。カーソルベースのページネーションに対応しています。

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

| パラメータ         | 型         | デフォルト  | 説明                                                    |
| ------------- | --------- | ------ | ----------------------------------------------------- |
| `active_only` | `boolean` | `true` | false を指定すると無効化したプレイブックも含めます。"true" / "false" 以外は 400 |
| `limit`       | `integer` | `50`   | 1 ページの取得件数（1-100）                                     |
| `cursor`      | `string`  | `—`    | 次ページ取得用カーソル（前回レスポンスの cursor 値）                        |

#### リクエスト例

**List playbooks**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?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）

| フィールド                              | 型                | 説明                                                                                          |
| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `playbooks`                        | `array`          | プレイブックオブジェクトの配列                                                                             |
| `playbooks[].playbookId`           | `string`         | プレイブック ID（Chat の playbookId に指定します）                                                         |
| `playbooks[].ownerUserId`          | `string`         | 持ち主の利用者 ID                                                                                  |
| `playbooks[].name`                 | `string`         | プレイブック名                                                                                     |
| `playbooks[].description`          | `string?`        | 説明                                                                                          |
| `playbooks[].category`             | `string?`        | カテゴリ                                                                                        |
| `playbooks[].tags`                 | `array`          | タグの配列（前後の空白を除き、空のタグを外し、同じタグは 1 つにして返します）                                                    |
| `playbooks[].steps`                | `array`          | 手順の配列                                                                                       |
| `playbooks[].steps[].title`        | `string`         | 手順のタイトル                                                                                     |
| `playbooks[].steps[].description`  | `string?`        | 手順の説明                                                                                       |
| `playbooks[].steps[].guidance`     | `array?`         | 補足指示の配列                                                                                     |
| `playbooks[].steps[].success`      | `string?`        | 完了条件                                                                                        |
| `playbooks[].sourceConversationId` | `string?`        | 作成元の会話 ID                                                                                   |
| `playbooks[].isShared`             | `boolean`        | 公開しているかどうか                                                                                  |
| `playbooks[].isActive`             | `boolean`        | 有効かどうか                                                                                      |
| `playbooks[].shareRequestStatus`   | `string \| null` | 公開の申請の状態（「スキル・プレイブックの公開の承認」を参照）。同じく shareRequestNote・shareReviewNote・shareRequestedAt も入ります |
| `playbooks[].usageCount`           | `number`         | 利用回数                                                                                        |
| `playbooks[].copyCount`            | `number`         | コピーされた回数                                                                                    |
| `playbooks[].createdAt`            | `string`         | 作成日時（ISO 8601）                                                                              |
| `playbooks[].updatedAt`            | `string`         | 最終更新日時（ISO 8601）                                                                            |
| `hasMore`                          | `boolean`        | 次のページが存在するかどうか                                                                              |
| `cursor`                           | `string`         | 次ページ取得用カーソル。hasMore が true の場合のみ含まれます                                                       |

#### レスポンス例

```json
{
  "playbooks": [
    {
      "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "name": "週次レポート作成",
      "description": "売上データから週次レポートを生成する",
      "category": "レポート",
      "tags": ["sales", "weekly"],
      "steps": [
        {
          "title": "データ取得",
          "description": "対象期間の売上データを取得する",
          "guidance": ["前週の月曜から日曜まで"],
          "success": "データが1件以上取得できている"
        }
      ],
      "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
      "isShared": false,
      "isActive": true,
      "shareRequestStatus": null,
      "shareRequestNote": null,
      "shareReviewNote": null,
      "shareRequestedAt": null,
      "usageCount": 12,
      "copyCount": 0,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

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

`hasMore` が `true` の間、レスポンスの `cursor` をそのまま次のリクエストに渡してください。

```bash
# 1ページ目
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=50" \
  -H "Authorization: Bearer <access_token>"

# 2ページ目（1ページ目のレスポンスに含まれる cursor を指定）
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=50&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"
```

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

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

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

| ステータス | 説明                                     |
| ----- | -------------------------------------- |
| `400` | limit が 1-100 の整数でない                   |
| `400` | cursor が不正（前回レスポンスの値以外）                |
| `400` | active\_only が "true" / "false" 以外     |
| `403` | chat:exec / assets:read のいずれも持っていない    |
| `403` | システム連携のトークンで呼び出した（`code: "forbidden"`） |

### GET`/v1/playbooks/shared`

公開されているプレイブックの一覧を取得します。自分が公開したものと、公開した人が無効にしたものも含みます。コピーされた回数の多い順（同数の場合は作成日時の新しい順）で返ります。カーソルベースのページネーションに対応しています。

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

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

#### リクエスト例

**List shared playbooks**

**curl**

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

**Python**

```python
import requests

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

print(response.json())
```

**TypeScript**

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

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared?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）

自分のプレイブックの一覧と同じ形です。ただし、各項目に `isShared`・`isActive` と申請の状態の項目は含まれません。

#### レスポンス例

```json
{
  "playbooks": [
    {
      "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "週次レポート作成",
      "description": "売上データから週次レポートを生成する",
      "category": "レポート",
      "tags": [
        "sales",
        "weekly"
      ],
      "steps": [
        {
          "title": "データ取得",
          "description": "対象期間の売上データを取得する",
          "guidance": [
            "前週の月曜から日曜まで"
          ],
          "success": "データが1件以上取得できている"
        }
      ],
      "usageCount": 12,
      "copyCount": 0,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

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

| ステータス | 説明                                     |
| ----- | -------------------------------------- |
| `400` | limit が 1-100 の整数でない                   |
| `400` | cursor が不正（前回レスポンスの値以外）                |
| `403` | chat:exec / assets:read のいずれも持っていない    |
| `403` | システム連携のトークンで呼び出した（`code: "forbidden"`） |

### GET`/v1/playbooks/:playbookId`

プレイブックを取得します。自分のプレイブックと、公開されているプレイブックを取得できます。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明               |
| ------------ | -------- | -- | ---------------- |
| `playbookId` | `string` | 必須 | プレイブックの ID（UUID） |

#### リクエスト例

**Get playbook**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
{
  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/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7", 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）

プレイブックの一覧の 1 件と同じ項目に、`digest` を加えた形です。ほかの利用者の公開プレイブックでは、公開の一覧と同じく `isShared`・`isActive` と申請の状態の項目は含まれません。

| フィールド    | 型        | 説明                                                                                 |
| -------- | -------- | ---------------------------------------------------------------------------------- |
| `digest` | `string` | プレイブックを変えるときに baseDigest に送る値。名前・説明・カテゴリ・タグ・手順・公開・有効から作られ、利用回数・コピーされた回数・日時では変わりません |

`updatedAt` は、内容を変えたときのほか、プレイブックが使われるたびにも更新されます。

#### レスポンス例

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "週次レポート作成",
  "description": "売上データから週次レポートを生成する",
  "category": "レポート",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "データ取得",
      "description": "対象期間の売上データを取得する",
      "guidance": [
        "前週の月曜から日曜まで"
      ],
      "success": "データが1件以上取得できている"
    }
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "usageCount": 12,
  "copyCount": 0,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
```

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

| ステータス | code                 | 説明                                |
| ----- | -------------------- | --------------------------------- |
| `400` | `invalid_parameter`  | playbookId が UUID の形式ではない         |
| `403` | `insufficient_scope` | assets:read スコープが不足               |
| `403` | `forbidden`          | システム連携のトークンで呼び出した                 |
| `404` | `playbook_not_found` | プレイブックが存在しない、またはほかの利用者の非公開のプレイブック |

### POST`/v1/playbooks`

プレイブックを作ります。

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

| フィールド                 | 型                | 必須 | 説明                                                                         |
| --------------------- | ---------------- | -- | -------------------------------------------------------------------------- |
| `name`                | `string`         | 必須 | 名前（100 文字まで。空白だけにはできません）                                                   |
| `description`         | `string \| null` | —  | 説明（500 文字まで）                                                               |
| `category`            | `string \| null` | —  | カテゴリ（50 文字まで）                                                              |
| `tags`                | `array`          | —  | タグ（1 つ 30 文字までの文字列を 10 個まで。空・空白だけのタグと、前後の空白を除いて同じになるタグは送れません。大文字小文字は区別します） |
| `steps`               | `array`          | 必須 | 手順（1〜20 個）                                                                 |
| `steps[].title`       | `string`         | 必須 | 手順のタイトル（100 文字まで。空白だけにはできません）                                              |
| `steps[].description` | `string`         | —  | 手順の説明（1000 文字まで）                                                           |
| `steps[].guidance`    | `array`          | —  | 補足指示（1 つ 500 文字までの文字列を 10 個まで。空・空白だけの文字列は送れません）                            |
| `steps[].success`     | `string`         | —  | 完了条件（500 文字まで）                                                             |
| `isShared`            | `boolean`        | —  | 公開するかどうか。省くと非公開                                                            |
| `isActive`            | `boolean`        | —  | 有効かどうか。省くと有効                                                               |
| `shareRequestNote`    | `string \| null` | —  | 公開の申請の理由（前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照）                        |

- 手順の項目は `title`・`description`・`guidance`・`success` の 4 つです（ほかの項目は保存しません）。手順の文字列の項目に `null` は送れません。
- 名前・説明・カテゴリは、前後の空白を除いて保存します。説明・カテゴリは、`null`・空の文字列・空白だけのときは `null` で保存します。

#### リクエスト例

**Create playbook**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "週次レポート作成",
  "description": "売上データから週次レポートを生成する",
  "category": "レポート",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "データ取得",
      "description": "対象期間の売上データを取得する",
      "guidance": [
        "前週の月曜から日曜まで"
      ],
      "success": "データが1件以上取得できている"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': '週次レポート作成', 'description': '売上データから週次レポートを生成する', 'category': 'レポート', 'tags': ['sales', 'weekly'], 'steps': [{'title': 'データ取得', 'description': '対象期間の売上データを取得する', 'guidance': ['前週の月曜から日曜まで'], 'success': 'データが1件以上取得できている'}]},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "週次レポート作成", "description": "売上データから週次レポートを生成する", "category": "レポート", "tags": ["sales", "weekly"], "steps": [{"title": "データ取得", "description": "対象期間の売上データを取得する", "guidance": ["前週の月曜から日曜まで"], "success": "データが1件以上取得できている"}]}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "週次レポート作成", "description": "売上データから週次レポートを生成する", "category": "レポート", "tags": ["sales", "weekly"], "steps": [{"title": "データ取得", "description": "対象期間の売上データを取得する", "guidance": ["前週の月曜から日曜まで"], "success": "データが1件以上取得できている"}]}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks", 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)
```

#### レスポンス（201 Created）

自分のプレイブックの取得と同じ形で、作ったプレイブックを返します。

#### レスポンス例

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": null,
  "name": "週次レポート作成",
  "description": "売上データから週次レポートを生成する",
  "category": "レポート",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "データ取得",
      "description": "対象期間の売上データを取得する",
      "guidance": [
        "前週の月曜から日曜まで"
      ],
      "success": "データが1件以上取得できている"
    }
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "usageCount": 0,
  "copyCount": 0,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
```

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

| ステータス | code                     | 説明                                                                                |
| ----- | ------------------------ | --------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | name・steps が無い、または項目の型や長さ・数の誤り（error.param に誤った項目。手順の中は steps\[2].title のように示します） |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                 |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                              |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                 |
| `413` | `body_too_large`         | ボディが 3 MiB を超える                                                                   |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                         |

### PATCH`/v1/playbooks/:playbookId`

自分のプレイブックを変えます。送った項目だけを変えます。手順（`steps`）は、送ると全部が置き換わります（書き換え・削除・並べ替えは、この配列で表します）。

名前・説明・カテゴリ・タグ・手順のどれかを変えると、変える前の中身がバージョンとして残り、画面の「バージョンの履歴」から戻せます。公開・有効の切り替えだけでは残りません。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明               |
| ------------ | -------- | -- | ---------------- |
| `playbookId` | `string` | 必須 | プレイブックの ID（UUID） |

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

| フィールド              | 型                | 必須 | 説明                                                                  |
| ------------------ | ---------------- | -- | ------------------------------------------------------------------- |
| `baseDigest`       | `string`         | 必須 | プレイブックの取得の digest                                                   |
| `name`             | `string`         | —  | 名前（100 文字まで。空白だけや null にはできません）                                     |
| `description`      | `string \| null` | —  | 説明（500 文字まで）。null か空の文字列で空にします                                      |
| `category`         | `string \| null` | —  | カテゴリ（50 文字まで）。null か空の文字列で空にします                                     |
| `tags`             | `array`          | —  | タグ（1 つ 30 文字までの文字列を 10 個まで。送れないタグは作るときと同じです）。空にするときは \[]            |
| `steps`            | `array`          | —  | 手順の全部（1〜20 個）。項目はプレイブックを作るときと同じです                                   |
| `isShared`         | `boolean`        | —  | 公開するかどうか。公開の承認が有効なテナントでは、true で承認待ちになり、承認待ちのものに false を送ると申請を取り下げます |
| `isActive`         | `boolean`        | —  | 有効かどうか                                                              |
| `shareRequestNote` | `string \| null` | —  | 公開の申請の理由（前後の空白を除いて 2000 文字まで。「スキル・プレイブックの公開の承認」を参照）                 |

baseDigest のほかに、少なくとも 1 つの項目（shareRequestNote を除きます）を送ってください。`name`・`tags`・`steps`・`isShared`・`isActive` に `null` は送れません。保存のしかた（前後の空白）と、送れないタグ・補足指示は、プレイブックを作るときと同じです。

1 回目で内容が変わっていれば、送り直すと `digest` が変わっているため `409 Conflict`（`stale_base`）が返ります。取得し直して、変わったかを確かめてください。

公開の承認が有効なテナントで、承認待ちのプレイブックの中身（名前・説明・カテゴリ・タグ・手順）を変えると、承認待ちのまま、変えた後の内容で承認を待ちます。管理者が公開の承認をやめた後に、承認待ちのプレイブックの中身を変えると、その変更で公開されます。画面で変えた場合と同じです（[公開の承認](#assets-share-approval)）。

公開の承認が有効なテナントで、公開中のプレイブックの中身を変えると、公開を続けたまま申請になります（応答の `isShared` は `true`、`shareRequestStatus` は `"pending"`）。承認されるまで、ほかの利用者には承認した中身が見えます（[公開の承認](#assets-share-approval)）。

#### リクエスト例

**Update playbook**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E",
  "description": "売上データから週次レポートを作る"
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  headers={"Authorization": f"Bearer {token}"},
  json={'baseDigest': 'zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E', 'description': '売上データから週次レポートを作る'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E", "description": "売上データから週次レポートを作る"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E", "description": "売上データから週次レポートを作る"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7", 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)
```

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

自分のプレイブックの取得と同じ形で、変えた後のプレイブック（そのときの `digest`）を返します。

#### レスポンス例

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "週次レポート作成",
  "description": "売上データから週次レポートを作る",
  "category": "レポート",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "データ取得",
      "description": "対象期間の売上データを取得する",
      "guidance": [
        "前週の月曜から日曜まで"
      ],
      "success": "データが1件以上取得できている"
    }
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "usageCount": 12,
  "copyCount": 0,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "digest": "DYEcDfkGIG6oOpm-WEd7l1UhFjZzruLKxM9yEYu9BTA"
}
```

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

| ステータス | code                     | 説明                                                                                            |
| ----- | ------------------------ | --------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | playbookId が UUID の形式ではない、baseDigest が無い・空・文字列ではない、変える項目が無い、項目の型や長さ・数の誤り、または送れない項目に null を送った |
| `400` | `invalid_body`           | ボディが壊れた JSON、または JSON のオブジェクトではない                                                             |
| `403` | `insufficient_scope`     | assets:write スコープが不足                                                                          |
| `403` | `forbidden`              | システム連携のトークンで呼び出した                                                                             |
| `404` | `playbook_not_found`     | プレイブックが存在しない、またはほかの利用者のプレイブック                                                                 |
| `409` | `stale_base`             | 取得した後にプレイブックが変わっている                                                                           |
| `413` | `body_too_large`         | ボディが 3 MiB を超える                                                                               |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                     |

### DELETE`/v1/playbooks/:playbookId`

自分のプレイブックを消します。システム管理者は、ほかの利用者が公開したプレイブックも消せます。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明               |
| ------------ | -------- | -- | ---------------- |
| `playbookId` | `string` | 必須 | プレイブックの ID（UUID） |

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

| パラメータ   | 型        | デフォルト     | 説明                                                                           |
| ------- | -------- | --------- | ---------------------------------------------------------------------------- |
| `force` | `string` | `"false"` | "true" を指定すると、このプレイブックを使っているスケジュールや Agent があっても消します。"true" / "false" 以外は 400 |

- **使っているとき**: このプレイブックを使う有効なスケジュールか、このプレイブックを定義に持つ Agent があると、`409 Conflict`（`has_active_references`。使っている有効なスケジュールと Agent の数は `error.message`）が返ります。Agent は持ち主を問わず数えます。プロジェクトのジョブ（プロジェクトに置いた Agent の巡回と、まだ動き始めていないプロジェクトの実行）は、スケジュールとしては数えません。

- **`force=true` のとき**: このプレイブックを定義に持つ全員の Agent から外して、プレイブックを消します。外した Agent の巡回は、外した後の定義で動き続けます。有効なスケジュールが使っているときは、このプレイブックを使うスケジュールを、無効なものも含めて消します。

  <!-- -->

  - 数えて消すスケジュールは、自分のスケジュールだけです（システム管理者が自分のプレイブックを消すときも同じです）。ほかの利用者のスケジュールは数えず、消しません（消えたプレイブックを指したままになります）。システム管理者が、ほかの利用者が公開したプレイブックを消すときは、すべての利用者のスケジュールを数えて消します。
  - 使っているのが無効なスケジュールだけのときは、Agent も使っていなければ `409 Conflict` になりません。どちらのときも、`force=true` を付けても無効なスケジュールは消えず、消えたプレイブックを指したままになります。
  - 消えたスケジュールは、この後は動きません（すでに動き始めた実行は止まりません）。

#### リクエスト例

**Delete playbook**

**curl**

```curl
curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  headers={"Authorization": f"Bearer {token}"},
  params={"force": "false"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7" + "?force=false",
{
  method: "DELETE",
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

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

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "deleted": true
}
```

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

| ステータス | code                    | 説明                                                                 |
| ----- | ----------------------- | ------------------------------------------------------------------ |
| `400` | `invalid_parameter`     | playbookId が UUID の形式ではない、または force が "true" / "false" 以外          |
| `403` | `insufficient_scope`    | assets:delete スコープが不足                                              |
| `403` | `forbidden`             | システム連携のトークンで呼び出した                                                  |
| `404` | `playbook_not_found`    | プレイブックが存在しない、またはほかの利用者のプレイブックで消せない                                 |
| `409` | `has_active_references` | 有効なスケジュールか Agent が使っている（force=true で消せます）                          |
| `409` | `admin_stopped`         | force=true で消すとき、このプレイブックを有効なスケジュールが使っていて、使っているスケジュールに管理者が止めたものがある |

### POST`/v1/playbooks/:playbookId/copy`

公開されているプレイブックを、自分のプレイブックとしてコピーします。名前・説明・カテゴリ・タグ・手順を写し、非公開・有効で作ります。コピー元のコピーされた回数（`copyCount`）が 1 増えます。ボディは不要です（送っても読みません）。

#### パスパラメータ

| パラメータ        | 型        | 必須 | 説明                    |
| ------------ | -------- | -- | --------------------- |
| `playbookId` | `string` | 必須 | コピーするプレイブックの ID（UUID） |

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

| ヘッダー              | 必須 | 説明                                                                     |
| ----------------- | -- | ---------------------------------------------------------------------- |
| `Idempotency-Key` | —  | 送り直しを見分けるキー（英数字と \_ . : - の 8〜128 文字）。同じキーで送り直すと、新しく作らずに、1 回目のコピーを返します |

#### リクエスト例

**Copy playbook**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: copy-playbook-20261118-0001"
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-playbook-20261118-0001"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "copy-playbook-20261118-0001",
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-playbook-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### レスポンス（201 Created）

自分のプレイブックの取得と同じ形で、コピーして作ったプレイブックを返します。

同じ `Idempotency-Key` で送り直したときは、`200 OK` で、1 回目のコピー（今の内容）を同じ形で返します。1 回目のコピーが消されていると `404 Not Found`（`playbook_not_found`）が返ります。新しいキーで送ってください。

#### レスポンス例

```json
{
  "playbookId": "1d3f5a7b-9c2e-4a6c-8e0f-2b4d6f8a0c1e",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": null,
  "name": "週次レポート作成",
  "description": "売上データから週次レポートを生成する",
  "category": "レポート",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "データ取得",
      "description": "対象期間の売上データを取得する",
      "guidance": [
        "前週の月曜から日曜まで"
      ],
      "success": "データが1件以上取得できている"
    }
  ],
  "isShared": false,
  "isActive": true,
  "shareRequestStatus": null,
  "shareRequestNote": null,
  "shareReviewNote": null,
  "shareRequestedAt": null,
  "usageCount": 0,
  "copyCount": 0,
  "createdAt": "2026-11-18T05:00:00.000Z",
  "updatedAt": "2026-11-18T05:00:00.000Z",
  "digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
```

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

| ステータス | code                      | 説明                                                                                                   |
| ----- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`       | playbookId が UUID の形式ではない                                                                            |
| `400` | `idempotency_key_invalid` | Idempotency-Key の形式が誤っている                                                                            |
| `403` | `insufficient_scope`      | assets:write スコープが不足                                                                                 |
| `403` | `forbidden`               | システム連携のトークンで呼び出した                                                                                    |
| `404` | `playbook_not_found`      | プレイブックが存在しない、公開されていない（自分のプレイブックでも、公開していなければ 404）、または同じ Idempotency-Key で作ったコピーが消されている（新しいキーで送ってください） |
| `409` | `idempotency_conflict`    | 同じ Idempotency-Key で、別のプレイブックのコピーを送った                                                                |

## 検索

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

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

| メソッド | エンドポイント               | 説明         | スコープ (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://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=売上" \
-H "Authorization: Bearer <access_token>"
```

**Python**

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

query = "売上"
response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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://api.fd.agenticstar.tm.softbank.jp/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 が読めない |
| `403` | chat:history スコープが不足                                                                                                |
| `501` | 検索の設定が無い環境（`code: "search_not_configured"`）                                                                         |
| `503` | 検索が一時的に使えない（`code: "service_unavailable"`）。時間をおいて送り直してください                                                          |

## ユーザー

ユーザー情報の取得・更新・パスワード変更を行います。

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

| メソッド  | エンドポイント             | 説明        |
| ----- | ------------------- | --------- |
| GET   | `/v1/user`          | ユーザー情報を取得 |
| PATCH | `/v1/user`          | ユーザー情報を更新 |
| POST  | `/v1/user/password` | パスワードを変更  |

### GET`/v1/user`

ユーザー情報を取得します。

#### リクエスト例

**Get user**

**curl**

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

**Python**

```python
import requests

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

user = response.json()
print(f"User: {user['username']} ({user['email']})")
```

**TypeScript**

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

const user = await response.json();
console.log("User: " + user.username + " (" + user.email + ")");
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

var user map[string]interface{}
json.NewDecoder(resp.Body).Decode(&user)
fmt.Printf("User: %s (%s)\n", user["username"], user["email"])
```

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

| フィールド                | 型         | 説明                          |
| -------------------- | --------- | --------------------------- |
| `userId`             | `string`  | ユーザーの一意識別子                  |
| `email`              | `string`  | メールアドレス                     |
| `username`           | `string`  | ユーザー名                       |
| `emailVerified`      | `boolean` | メールアドレスの確認状態                |
| `createdAt`          | `string`  | アカウント作成日時（ISO 8601）         |
| `isApproved`         | `boolean` | アカウントの承認状態                  |
| `role`               | `string`  | ユーザーのロール                    |
| `organization`       | `object`  | 所属組織（設定されている場合のみ）           |
| `organization.value` | `string`  | 組織コード                       |
| `organization.label` | `string`  | 組織名                         |
| `jobType`            | `object`  | 職種（設定されている場合のみ）             |
| `jobType.value`      | `string`  | 職種コード                       |
| `jobType.label`      | `string`  | 職種名                         |
| `bio`                | `string`  | 自己紹介（設定されている場合のみ）           |
| `lastLoginAt`        | `string`  | 最終ログイン日時（ISO 8601、存在する場合のみ） |

#### レスポンス例

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "田中太郎",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "エンジニアリング部門" },
  "jobType": { "value": "dev", "label": "開発者" },
  "bio": "AIエンジニア",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

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

| ステータス | code             | 説明                               |
| ----- | ---------------- | -------------------------------- |
| `500` | `internal_error` | ユーザー情報を取得できなかった（時間をおいて再試行してください） |

### PATCH`/v1/user`

ユーザー情報を更新します。

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

| パラメータ          | 型        | 必須 | 説明                                                                                                                              |
| -------------- | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------- |
| `username`     | `string` | —  | ユーザー名。2〜50 文字で、「<」「>」「"」「'」は使えません                                                                                               |
| `organization` | `string` | —  | 組織コード。100 文字まで。未設定のときだけ設定でき、有効な組織コードだけを設定できます。設定済みの組織を変える（空にするのも）と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤（IdP）で変えてください |
| `jobType`      | `string` | —  | 職種コード。100 文字まで。未設定のときだけ設定でき、有効な職種コードだけを設定できます。設定済みの職種を変える（空にするのも）と 403 になります。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤（IdP）で変えてください |
| `bio`          | `string` | —  | 自己紹介。150 文字までで、「<」「>」「"」「'」は使えません                                                                                               |

#### リクエスト例

**Update user**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "username": "田中太郎", "bio": "エンジニアリング部門" }'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
  headers={"Authorization": f"Bearer {token}"},
  json={"username": "田中太郎", "bio": "エンジニアリング部門"},
)

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

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    username: "田中太郎",
    bio: "エンジニアリング部門",
  }),
}
);

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

**Go**

```go
payload := map[string]string{
  "username": "田中太郎",
  "bio": "エンジニアリング部門",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("PATCH",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

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

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

GET /v1/user と同じユーザーオブジェクトが返されます（更新後の値を含む）。

#### レスポンス例

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "田中太郎",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "エンジニアリング部門" },
  "jobType": { "value": "dev", "label": "開発者" },
  "bio": "エンジニアリング部門",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

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

| ステータス | code                     | 説明                                                                                                               |
| ----- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter`      | 更新するフィールドが未指定                                                                                                    |
| `400` | `invalid_body`           | ボディが壊れた JSON                                                                                                     |
| `400` | `invalid_parameter`      | 入力の誤り（username / organization / jobType / bio が文字列ではない、文字数・使えない文字、または初めて設定する organization / jobType が有効なコードではない） |
| `403` | `affiliation_locked`     | 設定済みの organization / jobType を変えようとした（空にするのも）。変更は管理者に依頼してください。IdP から同期しているときは、ID 基盤（IdP）で変えてください                 |
| `409` | `conflict`               | 同じユーザーの別の更新を処理している。少し待ってから送り直してください                                                                              |
| `415` | `unsupported_media_type` | ボディの Content-Type が application/json ではない                                                                        |

### POST`/v1/user/password`

パスワードを変更します。

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

| パラメータ             | 型        | 必須 | 説明            |
| ----------------- | -------- | -- | ------------- |
| `currentPassword` | `string` | 必須 | 現在のパスワード      |
| `newPassword`     | `string` | 必須 | 新しいパスワード      |
| `confirmPassword` | `string` | 必須 | 新しいパスワード（確認用） |

#### リクエスト例

**Change password**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!",
  "confirmPassword": "NewPass456!"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
  headers={"Authorization": f"Bearer {token}"},
  json={
      "currentPassword": "OldPass123!",
      "newPassword": "NewPass456!",
      "confirmPassword": "NewPass456!",
  },
)

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

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currentPassword: "OldPass123!",
    newPassword: "NewPass456!",
    confirmPassword: "NewPass456!",
  }),
}
);

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

**Go**

```go
payload := map[string]string{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!",
  "confirmPassword": "NewPass456!",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

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

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

| フィールド     | 型         | 説明                 |
| --------- | --------- | ------------------ |
| `userId`  | `string`  | ユーザーの一意識別子         |
| `changed` | `boolean` | パスワード変更成功時は常に true |

#### レスポンス例

```json
{ "userId": "user-abc123", "changed": true }
```

パスワードを変えたら、変える前に取ったトークンは使い続けず、もう一度ログインしてトークンを取り直してください。変える前のアクセストークンは、期限まで API に通ります。

パスワードを変えると、本人のチャットの画面のログインも、すべての端末で、次に操作したときに切れます。

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

| ステータス | 説明                                                                                                                                     |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | 必須パラメータの不足、currentPassword / newPassword / confirmPassword が文字列ではない、ボディが壊れた JSON（`code: "invalid_body"`）、パスワードバリデーション失敗、または現在のパスワードが不正 |
| `415` | ボディの Content-Type が application/json ではない（`code: "unsupported_media_type"`）                                                            |
| `401` | 認証トークンが無効                                                                                                                              |
| `403` | SSO でログインする利用者（`code: "federation_only_user"`）。SSO の利用者は、この API でパスワードを変えられません                                                         |

## マスターデータ

組織・ジョブタイプ等のマスターデータを取得します。

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

| メソッド | エンドポイント             | 説明          |
| ---- | ------------------- | ----------- |
| GET  | `/v1/organizations` | 組織一覧を取得     |
| GET  | `/v1/job-types`     | ジョブタイプ一覧を取得 |
| GET  | `/v1/personas`      | ペルソナ一覧を取得   |

### GET`/v1/organizations`

組織一覧を取得します。無効化された組織は含まれません。

#### リクエスト例

**List organizations**

**curl**

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

**Python**

```python
import requests

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

data = response.json()
for org in data["organizations"]:
  print(f"{org['value']}: {org['label']}")
```

**TypeScript**

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

const data = await response.json();
data.organizations.forEach((org) => {
console.log(org.value + ": " + org.label);
});
```

**Go**

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

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

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

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

| フィールド                   | 型         | 説明                    |
| ----------------------- | --------- | --------------------- |
| `organizations`         | `array`   | 組織オブジェクトの配列           |
| `organizations[].value` | `string`  | 組織コード                 |
| `organizations[].label` | `string`  | 組織名                   |
| `hasMore`               | `boolean` | 常に false（ページネーション非対応） |

#### レスポンス例

```json
{
  "organizations": [
    { "value": "eng", "label": "エンジニアリング部門" },
    { "value": "sales", "label": "営業部門" }
  ],
  "hasMore": false
}
```

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

| ステータス | code             | 説明                              |
| ----- | ---------------- | ------------------------------- |
| `500` | `internal_error` | 組織の一覧を取得できなかった（時間をおいて再試行してください） |

### GET`/v1/job-types`

ジョブタイプ一覧を取得します。無効化されたジョブタイプは含まれません。

#### リクエスト例

**List job types**

**curl**

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

**Python**

```python
import requests

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

job_types = response.json()["jobTypes"]
for jt in job_types:
  print(f"{jt['value']}: {jt['label']}")
```

**TypeScript**

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

const data = await response.json();
data.jobTypes.forEach((jt) => {
console.log(jt.value + ": " + jt.label);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types",
  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）

| フィールド              | 型         | 説明                    |
| ------------------ | --------- | --------------------- |
| `jobTypes`         | `array`   | ジョブタイプオブジェクトの配列       |
| `jobTypes[].value` | `string`  | 職種コード                 |
| `jobTypes[].label` | `string`  | 職種名                   |
| `hasMore`          | `boolean` | 常に false（ページネーション非対応） |

#### レスポンス例

```json
{
  "jobTypes": [
    { "value": "dev", "label": "開発者" },
    { "value": "pm", "label": "プロジェクトマネージャー" }
  ],
  "hasMore": false
}
```

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

| ステータス | code             | 説明                                  |
| ----- | ---------------- | ----------------------------------- |
| `500` | `internal_error` | ジョブタイプの一覧を取得できなかった（時間をおいて再試行してください） |

### GET`/v1/personas`

ペルソナ（エージェントの応答人格）一覧を取得します。取得した `personaKey` を Chat / MCP / A2A の persona 指定に使用します。

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

| パラメータ    | 型        | 必須 | デフォルト          | 説明                                                                                      |
| -------- | -------- | -- | -------------- | --------------------------------------------------------------------------------------- |
| `locale` | `string` | —  | `プラットフォーム既定言語` | name / description の表示言語（例: "ja"、"en"）。知らない値や文字列ではない値を指定しても 400 にはならず、プラットフォーム既定言語で返します |

#### リクエスト例

**List personas**

**curl**

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

**Python**

```python
import requests

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

for persona in response.json()["personas"]:
  print(persona["personaKey"], persona["name"])
```

**TypeScript**

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

const data = await response.json();
data.personas.forEach((persona) => {
console.log(persona.personaKey + " " + persona.name);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas?locale=ja",
  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["personas"])
```

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

| フィールド                    | 型         | 説明                                                       |
| ------------------------ | --------- | -------------------------------------------------------- |
| `locale`                 | `string`  | 解決されたロケール。指定した言語の内容が無いペルソナは、英語、日本語、ほかの言語の順で、別の言語の内容で返ります |
| `personas`               | `array`   | ペルソナオブジェクトの配列                                            |
| `personas[].personaKey`  | `string`  | ペルソナの識別子（Chat / MCP / A2A の personaKey に指定）              |
| `personas[].name`        | `string`  | ペルソナの表示名                                                 |
| `personas[].description` | `string`  | ペルソナの説明                                                  |
| `hasMore`                | `boolean` | 常に false（ページネーション非対応）                                    |

#### レスポンス例

```json
{
  "locale": "ja",
  "personas": [
    { "personaKey": "concise", "name": "簡潔", "description": "要点に絞って簡潔に回答します" }
  ],
  "hasMore": false
}
```

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

| ステータス | code             | 説明                                |
| ----- | ---------------- | --------------------------------- |
| `500` | `internal_error` | ペルソナの一覧を取得できなかった（時間をおいて再試行してください） |

## プロジェクト

プロジェクトの API は、[ユーザー API リファレンス（プロジェクト）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md)に載せています。システム連携（Client Credentials フロー）のトークンで呼ぶときは、[システム連携 API リファレンス — プロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/admin-api-reference.md#projects)を参照してください。

### プロジェクト一覧の取得

`GET /v1/projects` は、[ユーザー API リファレンス（プロジェクト）のプロジェクト](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#projects)に載せています。

### ワークフローの実行の開始

`POST /v1/projects/{projectId}/runs` は、[ユーザー API リファレンス（プロジェクト）のワークフローの実行（run）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#runs)に載せています。

### トリガーの発火

`POST /v1/projects/{projectId}/triggers/{triggerId}/fire` は、[ユーザー API リファレンス（プロジェクト）のトリガー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#triggers)に載せています。

### ワークフローの実行の取得

`GET /v1/projects/{projectId}/runs/{runId}` は、[ユーザー API リファレンス（プロジェクト）のワークフローの実行（run）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference-projects.md#runs)に載せています。

## エラーレスポンス

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

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

| ステータス                        | 説明                                                                                                                                                                                        |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | リクエストパラメータが不正                                                                                                                                                                             |
| `401 Unauthorized`           | トークンが無効または未指定。管理者に利用を止められた利用者のトークンでも返ります（下の「利用を止められた利用者」）                                                                                                                                 |
| `403 Forbidden`              | リソースへのアクセス権限なし。管理者が公開 API の接続元を制限していて、接続元の IP アドレスが許可の一覧に無いときも返ります（`error.code` は `ip_not_allowed`）                                                                                       |
| `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/personas`・`GET /v1/user`・`PATCH /v1/user`、MCP の `list_personas` と、進行中のタスクが無いときの `cancel_chat`。止められた後も、アクセストークンの有効期限までは呼べます。止められた利用者は、アクセストークンを更新できません。

### 前段の仕組みで止められたとき

API の前段の仕組み（セキュリティの検査など）が HTML のエラー画面を返した場合は、上の共通の形の JSON に置き換えて返します。このときの `error.code` は次のとおりです。

| ステータス           | error.code           | 説明                                                                                                           |
| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
| 403             | `waf_blocked`        | リクエストが、API の前段にあるセキュリティの検査に止められました。正当なリクエストの場合は、`error.reference`（無い場合は応答ヘッダーの `x-request-id`）を添えてお問い合わせください |
| 403 以外の 4xx・5xx | `upstream_api_error` | リクエストが、API の前段の仕組みで拒否されたか、そこでエラーになりました。続く場合は、`error.reference`（無い場合は応答ヘッダーの `x-request-id`）を添えてお問い合わせください    |

| フィールド             | 型        | 説明                                                  |
| ----------------- | -------- | --------------------------------------------------- |
| `error.reference` | `string` | 前段の仕組みで止められたときの参照番号。お問い合わせのときに添えてください。値が無い場合は含まれません |

```json
{
  "error": {
    "type": "forbidden_error",
    "message": "The request was blocked by a web application firewall before it reached the API.",
    "code": "waf_blocked",
    "suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
    "reference": "20261018T012345Z-0123456789abcdef"
  }
}
```
