# User API Reference (Conversations, Library, Organizations)

Endpoint specification and error codes for the user-facing API of the SaaS edition. For APIs called from a system integration, see the [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md). For the Marketplace edition, see the [System Integration API Reference (Marketplace)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md).

## Base URL

Send all API requests to the following base URL.

SaaS

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

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

## Authentication

Every API request must include a Bearer token in the `Authorization` header. This page describes calls with a token obtained by an application (Authorization Code flow). A token of a system integration (Client Credentials flow) cannot hold chat scopes, so it cannot be used for chat (it can call part of projects; see [System Integration API Reference — Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md#projects)).

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

If the token is missing or invalid, `401 Unauthorized` is returned. Some endpoints require additional scopes; if a required scope is missing, `403 Forbidden` is returned.

For how to obtain a token and for scope details, see the [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md) and the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/auth-saas-ref.md).

## Common Rules

These rules apply to the APIs on this page.

### How requests are handled

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

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

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

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

### Pagination

List endpoints support cursor-based pagination.

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

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

Cursor-based pagination is available on the list endpoints of [Conversations](#conversations), [Messages](#conversations), [Files](#file-management), [Message search](#search-messages), [Library](#library), [Agents](#agents), [Skills](#skills), [Playbooks](#playbooks) and [Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#projects). Treat `cursor` as opaque: do not interpret it, just pass the previous value back.

The skill version list (`GET /v1/skills/:skillId/versions`) does not support pagination. It returns up to 100 versions, newest first, and `hasMore` is always `false`.

## Chat

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

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

SSE Streaming Guide

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

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

### Endpoint List

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

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

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

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

#### Request Headers

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

#### Request Body

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

#### Edition-Specific Parameters

SaaS

|                    |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentLevel`       | `string`  | "default" or "high\_performance". Defaults to "default" when omitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `agentMode`        | `boolean` | Enable/disable agent mode. Defaults to true when omitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `privateMode`      | `boolean` | Enable/disable private mode. Defaults to false when omitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `reportMode`       | `string`  | "with" (default) or "without". Controls whether a work report is generated on completion.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `personaKey`       | `string`  | Specifies the persona (response character) for the agent. Pass a personaKey returned by `GET /v1/personas`. If omitted, no persona is applied. A value not in the list returns 400.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `playbookId`       | `string`  | Playbook (predefined procedure) to apply. Specify a playbookId returned by `GET /v1/playbooks`. Omit to apply no playbook. Returns 400 if the ID does not exist or has been deactivated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `skillIds`         | `array`   | Array of skill IDs to load into the agent (up to 10). Specify skillId values returned by `GET /v1/skills`. Returns 400 if 11 or more are specified. IDs that do not exist or are unavailable are ignored, and execution continues with the remaining skills.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `outputFormat`     | `string`  | Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept, and links become "text (URL)"). "markdown" preserves Markdown as-is.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `interactionReply` | `object`  | A mark that the message answers the agent's question. In the form `{ interactionId, optionIndex? }`, send the `interactionId` of a question waiting for an answer in this conversation (`delta.interaction.interactionId` in streaming, or `tasks[].metadata.interactionId` in the conversation history) and, for an answer chosen from the options, the number of the chosen option (0 to 9, starting from 0). With it, the message is recorded as the answer to that question, and you can answer even after the monthly usage limit is used up. Send it with `conversationId`. 400 (`invalid_parameter`) if it is malformed, has an unknown field, is not the ID of a question waiting for an answer in this conversation, or the number is outside the options. |

#### Message Object

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

#### Content Parts (Array Format)

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

| type           | Parameter                     | Description                                                                                                                                               |
| -------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"text"`       | `text (string)`               | Text message                                                                                                                                              |
| `"input_file"` | `fileId or filepath (string)` | Either the `fileId` of an uploaded file or the `filepath` of a library file returned by `GET /v1/library` (exactly one). Up to 20 files total per request |

#### Request Example

**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": "Please analyze the sales data"
    }
  ]
}'
```

**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": "Please analyze the sales data"}],
  },
  stream=True,
)

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

**TypeScript**

```typescript
const response = await fetch(
"https://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: "Please analyze the sales data" }],
  }),
}
);

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

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

**Go**

```go
package main

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

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

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

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

#### Response Headers

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

#### SSE Response Format

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

SSE Event Flow

1

<!-- -->

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

2

<!-- -->

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

3

<!-- -->

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

4

<!-- -->

. `data: [DONE]`

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

#### Response Example

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

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

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

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

data: [DONE]
```

#### Error Response

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

| Status | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input\_file parts in a single request, or reportMode other than "with" / "without"). A malformed JSON body (`code: "invalid_body"`). Or the specified conversationId is archived (`code: "conversation_archived"`). Or `interactionReply` is malformed, has an unknown field, is not the ID of a question waiting for an answer in this conversation, or its number is outside the options (`code: "invalid_parameter"`; `param` is `interactionReply`, or the name of a field with `interactionReply.` in front, such as `interactionReply.interactionId`), or `interactionReply` was sent without `conversationId` (`code: "missing_parameter"`) |
| `400`  | The messages array has no message with the user role (`code: "no_user_message"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `400`  | personaKey is not in the list returned by `GET /v1/personas` (`code: "invalid_parameter"`, `param: "personaKey"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `400`  | The playbook for playbookId does not exist (`code: "playbook_not_found"`) or is disabled (`code: "playbook_not_active"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `403`  | Missing chat:exec scope, or the specified conversation is a project conversation (`code: "project_conversation"`. Messages cannot be sent to a project conversation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `404`  | The `fileId` or `filepath` of the specified input\_file was not found (`code: "file_not_found"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | The specified conversation is currently being processed (`code: "conversation_processing"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `403`  | An administrator has not permitted agent mode, and the request uses it (agentMode is true, which is also the default when omitted) (`code: "feature_not_permitted"`, `param: "agentMode"`). Retry with agentMode set to false, or ask the administrator to permit it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `503`  | Feature permissions could not be checked (`code: "feature_permissions_unavailable"`). Wait and retry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

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

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

#### Path Parameters

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

#### Request Example

**Resume SSE stream**

**curl**

```curl
curl https://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())
}
```

#### Response (200 OK)

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

#### Error Response

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

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

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

#### Path Parameters

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

#### Request Body (optional)

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

#### Request Example

**Cancel chat**

**curl**

```curl
curl -X POST https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

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

## Conversation Management

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

### Endpoint List

| メソッド   | エンドポイント                                                      | 説明                            | Scope (SaaS)                    |
| ------ | ------------------------------------------------------------ | ----------------------------- | ------------------------------- |
| GET    | `/v1/conversations`                                          | List conversations            | `chat:history`                  |
| GET    | `/v1/conversations/:conversationId/messages`                 | Get message history           | `chat:history`                  |
| GET    | `/v1/conversations/:conversationId/ui-resources/:toolCallId` | Get the HTML of a UI resource | `chat:exec / a2a:all / mcp:all` |
| PATCH  | `/v1/conversations/:conversationId`                          | Update conversation title     | `chat:history`                  |
| DELETE | `/v1/conversations/:conversationId`                          | Delete a conversation         | `chat:history`                  |
| POST   | `/v1/conversations/:conversationId/restore`                  | Restore archived conversation | `chat:history`                  |
| POST   | `/v1/conversations/:conversationId/read`                     | Mark a conversation as read   | `chat:history`                  |

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

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

#### Operations on archived conversations

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

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

### GET`/v1/conversations`

List conversations. Supports cursor-based pagination.

#### Query Parameters

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

#### Request Example

**List conversations**

**curl**

```curl
curl "https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

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

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

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

#### Path Parameters

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

#### Query Parameters

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

#### Request Example

**Get messages**

**curl**

```curl
curl https://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)
```

#### Response Fields (200 OK)

| Field                                 | Type              | Description                                                                                                                                                                                                                                                                |
| ------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`                            | `array`           | Array of message objects                                                                                                                                                                                                                                                   |
| `messages[].conversationId`           | `string`          | Conversation ID (UUID)                                                                                                                                                                                                                                                     |
| `messages[].messageId`                | `string`          | Unique identifier of the message                                                                                                                                                                                                                                           |
| `messages[].sender`                   | `string`          | Sender. "User" or "AI"                                                                                                                                                                                                                                                     |
| `messages[].text`                     | `string`          | The message body text. If the body is empty, the result (`content`) of the latest task is returned                                                                                                                                                                         |
| `messages[].createdAt`                | `string`          | Creation date and time (ISO 8601)                                                                                                                                                                                                                                          |
| `messages[].updatedAt`                | `string`          | Last updated date and time (ISO 8601)                                                                                                                                                                                                                                      |
| `messages[].status`                   | `object`          | Message processing status                                                                                                                                                                                                                                                  |
| `messages[].status.processing`        | `boolean`         | Whether the agent is currently processing                                                                                                                                                                                                                                  |
| `messages[].status.unfinished`        | `boolean`         | Whether the agent response was interrupted                                                                                                                                                                                                                                 |
| `messages[].tasks`                    | `array`           | Array of tasks executed by the agent (see below)                                                                                                                                                                                                                           |
| `messages[].deliverables`             | `array`           | Array of artifacts generated by the agent. Included only when present                                                                                                                                                                                                      |
| `messages[].deliverables[].filename`  | `string`          | Artifact file name                                                                                                                                                                                                                                                         |
| `messages[].deliverables[].filepath`  | `string`          | Artifact file path                                                                                                                                                                                                                                                         |
| `messages[].deliverables[].source`    | `string`          | `"agent"` (agent-generated) or `"user"` (user-uploaded)                                                                                                                                                                                                                    |
| `messages[].deliverables[].isPrimary` | `boolean`         | Whether it is a primary artifact                                                                                                                                                                                                                                           |
| `messages[].deliverables[].createdAt` | `string`          | Creation date and time (ISO 8601 format). An empty string when unknown                                                                                                                                                                                                     |
| `messages[].deliverables[].mimeType`  | `string`          | MIME type (e.g., `"application/pdf"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined                                                                                                                                                        |
| `messages[].deliverables[].size`      | `number?`         | File size (bytes). Omitted when 0 or below                                                                                                                                                                                                                                 |
| `messages[].files`                    | `array?`          | Array of user-uploaded files. Included only when present for messages with `sender: "User"`                                                                                                                                                                                |
| `messages[].files[].fileId`           | `string`          | Unique identifier of the file (UUID)                                                                                                                                                                                                                                       |
| `messages[].files[].mimeType`         | `string`          | MIME type (e.g., `"image/png"`, `"application/pdf"`)                                                                                                                                                                                                                       |
| `messages[].files[].width`            | `number?`         | Image width in pixels. Only for image files                                                                                                                                                                                                                                |
| `messages[].files[].height`           | `number?`         | Image height in pixels. Only for image files                                                                                                                                                                                                                               |
| `messages[].settings`                 | `object?`         | Settings used when the user message (sender: "User") was sent. Only saved items are included, and it is omitted when none are saved. Each item has the same meaning as the item of the same name in sending (POST /v1/chat/completions). Not included in archived messages |
| `messages[].settings.agentLevel`      | `string?`         | "default" / "high\_performance"                                                                                                                                                                                                                                            |
| `messages[].settings.agentMode`       | `boolean?`        | Agent mode                                                                                                                                                                                                                                                                 |
| `messages[].settings.privateMode`     | `boolean?`        | Private mode                                                                                                                                                                                                                                                               |
| `messages[].settings.reportMode`      | `string?`         | "with" / "without"                                                                                                                                                                                                                                                         |
| `messages[].settings.personaKey`      | `string \| null?` | Persona key. null when sent without choosing a persona                                                                                                                                                                                                                     |
| `messages[].settings.playbookId`      | `string?`         | Playbook ID                                                                                                                                                                                                                                                                |
| `messages[].settings.skillIds`        | `string[]?`       | Array of skill IDs                                                                                                                                                                                                                                                         |
| `messages[].archived`                 | `boolean?`        | `true` only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with `GET /v1/conversations?mode=archive`                                                                                                               |
| `hasMore`                             | `boolean`         | Whether a next page exists                                                                                                                                                                                                                                                 |
| `cursor`                              | `string`          | Cursor for the next page. Included only when hasMore is true                                                                                                                                                                                                               |

#### Task Object

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

#### UI resources (`tasks[].metadata.uiResource`)

When the agent produced a UI (a chart, a map, a card list, etc.) during execution, its metadata is included in `metadata.uiResource` of the corresponding task. **The HTML itself is not included.** Retrieve it with the [UI resource endpoint](#get-ui-resource).

The object has the same structure as in SSE. For field details, see [Streaming Guide — delta.uiResource](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-uiresource). The alternative text is in **`content` of the same task** (in SSE it is `delta.content` of the same chunk).

| Contents of metadata              | Meaning                                                                                                                                                                                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uiResource` only                 | Display-only UI. No user reply is expected.                                                                                                                                                                                                 |
| `uiResource` + `interaction_type` | UI that asks for a reply. `interaction_type` is `"choice"` or `"question"`. This combination occurs only with `origin: "first-party"`.                                                                                                      |
| `interaction_type` only           | A reply is requested but no UI is included. `interaction_type` is `"choice"` \| `"confirmation"` \| `"question"`. The reply instructions are in `content` of the same task.                                                                 |
| `options`                         | Array of choices (up to 10, each up to 200 characters). May be present independently of whether `interaction_type` is set.                                                                                                                  |
| `interactionId`                   | The ID of the agent's question. It may be absent (for example, for a question asked with a UI component). If this question is still waiting for an answer, you can use it in `interactionReply` of the next Chat API or MCP request         |
| `draft`                           | A draft made in the chat, together with `uiResource`. For its shape and how to create it, see [Streaming guide — delta.draft](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/streaming-guide.md#delta-draft) |

> **Discrimination differs from SSE**
>
> In SSE, `delta.uiResource` (display-only) and `delta.interaction.uiResource` (input) are separated structurally. In history and search, **both are placed in `tasks[].metadata.uiResource`**. Use the presence of `metadata.interaction_type` to tell them apart.

```json
{
  "status": "completed",
  "content": "Sales have grown for three consecutive quarters.",
  "metadata": {
    "uiResource": {
      "type": "html",
      "origin": "first-party",
      "altText": "Sales have grown for three consecutive quarters.",
      "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` is not included in history and search responses.

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

#### Response Example

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

#### Pagination

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

**Request example**

**curl**

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

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

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

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

#### Error Response

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

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

Retrieves the HTML of a UI resource. Pass the `tool_call_id` found in SSE [`delta.uiResource`](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-uiresource), in [`tasks[].metadata.uiResource`](#history-ui-resource) of history and search, or in the A2A and MCP responses.

Only `type: "html"` resources are retrievable. `type: "data"` carries its payload inline in the original response, so there is no need to call this endpoint for it.

> **The response is JSON**
>
> This endpoint does not return the HTML with `Content-Type: text/html`. It is not meant to be opened directly in a browser for rendering — it is **a retrieval point for your application to fetch the HTML**.

#### Required Scope

One of `chat:exec` / `a2a:all` / `mcp:all` is required. The scope of the channel through which you received the UI resource is enough. **`chat:history` is not accepted**, so a client using only the history API needs one of the scopes above.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                                                                                                                          |
| ---------------- | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversationId` | `string` | 必須 | Conversation ID (UUID)                                                                                                                      |
| `toolCallId`     | `string` | 必須 | Identifier of the UI resource — the value of uiResource.tool\_call\_id. Format: 1-128 characters of alphanumerics, hyphens, and underscores |

#### Request Example

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

#### Response Fields (200 OK)

| Field        | Type     | Description                                                                                                                    |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `toolCallId` | `string` | The UI resource identifier given in the request                                                                                |
| `type`       | `string` | Always `"html"`                                                                                                                |
| `origin`     | `string` | `"first-party"` (produced by AGENTIC STAR) or `"external"` (produced by an external MCP server approved by your administrator) |
| `mimeType`   | `string` | MIME type of the HTML. Normally `"text/html;profile=mcp-app"`                                                                  |
| `html`       | `string` | The HTML source                                                                                                                |

#### Response Example

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

#### Error Response

Use `code` to decide whether a retry makes sense.

| Status | code                      | Description                                                                | Retry                  |
| ------ | ------------------------- | -------------------------------------------------------------------------- | ---------------------- |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000) | No                     |
| `400`  | `invalid_parameter`       | Invalid toolCallId format                                                  | No                     |
| `403`  | `insufficient_scope`      | None of chat:exec / a2a:all / mcp:all is present                           | No                     |
| `404`  | `not_found`               | No such UI resource                                                        | No                     |
| `404`  | `conversation_not_found`  | No such conversation, or it belongs to another user                        | No                     |
| `404`  | `file_too_large`          | The HTML exceeds 512KB and cannot be returned                              | No (permanent failure) |
| `502`  | `upstream_api_error`      | Temporary retrieval failure                                                | Yes                    |
| `500`  | `internal_error`          | Other errors                                                               | Yes                    |

> **Notes on rendering**
>
> This endpoint returns **the HTML as a string**, and **rendering happens in your own application**. For whether you need a sandbox and how it differs by `origin`, see [Streaming Guide — Notes on rendering](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#rendering-notes).

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

Update the title of a conversation.

#### Path Parameters

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

#### Request Body

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

#### Request Example

**Update conversation**

**curl**

```curl
curl -X PATCH https://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": "New 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": "New 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: "New title" }),
}
);

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

**Go**

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

req, _ := http.NewRequest("PATCH",
  "https://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()
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

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

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

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

#### Path Parameters

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

#### Request Example

**Delete conversation**

**curl**

```curl
curl -X DELETE https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

| Status | code                      | Description                                                                                                 |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_conversation_id` | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted      |
| `400`  | `conversation_archived`   | The conversation is archived. Use `POST /v1/conversations/:id/restore` to restore it                        |
| `403`  | `insufficient_scope`      | The chat:history scope is missing                                                                           |
| `404`  | `conversation_not_found`  | The conversation was not found or is not yours                                                              |
| `409`  | `conversation_processing` | The conversation cannot be deleted because it is currently being processed                                  |
| `409`  | `project_conversation`    | A project conversation. Project conversations cannot be deleted                                             |
| `409`  | `claw_bound_conversation` | A conversation tied to a Claw schedule. First delete the Claw schedule tied to this conversation in the app |
| `409`  | `legal_hold`              | A conversation under legal hold. It cannot be deleted until an administrator releases the hold              |
| `503`  | `claw_binding_unverified` | Whether the conversation is tied to a Claw schedule could not be verified. Retry after a while              |

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

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

#### Path Parameters

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

#### Request Example

**Restore archived conversation**

**curl**

```curl
curl -X POST https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

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

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

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

In the SaaS edition, a personal schedule or Claw outside projects may be stopped when it has finished 3 or more runs in a row since it was last read and the oldest of them is 14 or more days ago (project sweeps are not affected). If you read the results through the API and do not want it to stop, mark the conversation as read with this API. Opening the conversation in the screen also marks it as read.

#### Path Parameters

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

#### Request Body (optional)

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

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

#### Request Example

**Mark a conversation as read**

**curl**

```curl
curl -X POST https://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"}'
```

#### Response (204 No Content)

There is no body.

#### Error Responses

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

## File Management

Upload, retrieve, and delete files.

### Endpoint List

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

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

### POST`/v1/files`

Upload a file.

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

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

#### Request Example

**Upload file**

**curl**

```curl
curl -X POST https://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())
```

#### Response Fields (201 Created)

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

#### Response Example

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

#### Error Response

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

### GET`/v1/files`

List files. Cursor-based pagination is supported.

#### Query Parameters

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

#### Request Example

**List files**

**curl**

```curl
curl https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Pagination

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

**Request example**

**curl**

```bash
# First page
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \
-H "Authorization: Bearer <access_token>"

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

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

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

#### Error Response

| Status | code                 | Description                                                |
| ------ | -------------------- | ---------------------------------------------------------- |
| `400`  | `invalid_parameter`  | limit is not an integer from 1 to 100                      |
| `400`  | `invalid_parameter`  | cursor is invalid (not a value from the previous response) |
| `400`  | `invalid_parameter`  | order is not "asc" / "desc"                                |
| `403`  | `insufficient_scope` | The chat:file scope is missing                             |

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

Download a file.

#### Path Parameters

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

#### Request Example

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

#### Response (200 OK)

The file binary data is returned as a stream.

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

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

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

#### Error Response

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

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

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

#### Path Parameters

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

#### Request Example

**Delete file**

**curl**

```curl
curl -X DELETE https://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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

| Status | code                 | Description                    |
| ------ | -------------------- | ------------------------------ |
| `400`  | `invalid_parameter`  | fileId has an invalid format   |
| `403`  | `insufficient_scope` | The chat:file scope is missing |
| `404`  | `file_not_found`     | The file was not found         |

## Artifact Retrieval

Retrieve artifact files generated by the agent.

### Endpoint List

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

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

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

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

<!-- -->

Any one of `chat:exec` / `a2a:all` / `mcp:all` is sufficient. Artifacts obtained through an A2A artifact or an MCP tool response can be downloaded here **with the scope of that same channel**.

<!-- -->

<!-- -->

Files in project execution results and review request evidence (`files[].filepath`) are not downloaded with this endpoint. Use [Get the content of a project file](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#get-project-file-content) (`GET /v1/projects/{projectId}/files/content`) instead.

<!-- -->

#### Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                                                                   |
| ------------ | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `path`       | `string` | 必須 | Artifact file path (obtained from deliverables\[].filepath in the message history)                                                   |
| `version_id` | `string` | —  | ID of a version of the file (versionId from the file library version list, GET /v1/library/versions). The current version if omitted |

#### Request Example

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

**Get artifact file**

**curl**

```curl
FILEPATH='<filepath>'

curl --get "https://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)
```

#### Response (200 OK)

The artifact file binary data is returned as a stream.

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

#### Error Response

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

## Library

Lists the user's library files (uploaded files and artifacts generated by the agent) across conversations. A returned `filepath` can be used to attach a file via Chat `input_file` or to download it through the artifact endpoint (`GET /v1/files/proxy`).

### Endpoints

| メソッド | エンドポイント                | 説明                                  | Scope (SaaS) |
| ---- | ---------------------- | ----------------------------------- | ------------ |
| GET  | `/v1/library`          | List library files                  | `chat:exec`  |
| GET  | `/v1/library/versions` | List the versions of a library file | `chat:exec`  |

### GET`/v1/library`

Retrieves the list of library files. Supports cursor-based pagination.

#### Query Parameters

| Parameter | Type      | Default  | Description                                                            |
| --------- | --------- | -------- | ---------------------------------------------------------------------- |
| `limit`   | `integer` | `50`     | Number of items to retrieve (1–100)                                    |
| `cursor`  | `string`  | `—`      | Cursor for the next page (the cursor value from the previous response) |
| `search`  | `string`  | `—`      | Filter by file name (partial match)                                    |
| `source`  | `string`  | `—`      | Filter by "agent" (agent-generated) or "user" (user-uploaded)          |
| `order`   | `string`  | `"desc"` | "asc" or "desc"                                                        |

#### Request Example

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

#### Response Fields (200 OK)

| Field                    | Type      | Description                                                                           |
| ------------------------ | --------- | ------------------------------------------------------------------------------------- |
| `files`                  | `array`   | Array of library file objects                                                         |
| `files[].filename`       | `string`  | File name                                                                             |
| `files[].filepath`       | `string`  | File path (used for Chat input\_file attachment or download via GET /v1/files/proxy)  |
| `files[].source`         | `string`  | "agent" (agent-generated) or "user" (user-uploaded)                                   |
| `files[].createdAt`      | `string`  | Creation timestamp (ISO 8601)                                                         |
| `files[].updatedAt`      | `string`  | Last update timestamp (ISO 8601)                                                      |
| `files[].mimeType`       | `string?` | MIME type. Omitted when it cannot be determined                                       |
| `files[].size`           | `number?` | File size in bytes. Omitted when unavailable                                          |
| `files[].conversationId` | `string?` | Associated conversation ID. Included only when the artifact is tied to a conversation |
| `hasMore`                | `boolean` | Whether a next page exists                                                            |
| `cursor`                 | `string`  | Cursor for the next page. Included only when hasMore is true                          |

#### Response Example

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

#### Error Responses

| Status | Description                                                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid limit (out of 1–100 range), cursor, source (other than "agent" / "user"), order (other than "asc" / "desc"), or search (not a string) |
| `403`  | Missing chat:exec scope                                                                                                                       |

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

Gets the versions of one library file, newest first. All versions are returned, and `hasMore` is always `false`. Get the content of a version by passing `versionId` as `version_id` of the artifact endpoint (`GET /v1/files/proxy`). For a file without version records, `versions` is an empty array and `currentVersionId` is null.

#### Query Parameters

| Parameter | Type     | Default | Description                                             |
| --------- | -------- | ------- | ------------------------------------------------------- |
| `path`    | `string` | `—`     | Required. The file path (filepath from GET /v1/library) |

#### Request Example

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

#### Response Fields (200 OK)

| Field                  | Type             | Description                                                |
| ---------------------- | ---------------- | ---------------------------------------------------------- |
| `filepath`             | `string`         | The file path                                              |
| `currentVersionId`     | `string \| null` | ID of the current version. null when there are no versions |
| `versions`             | `array`          | Array of versions (newest first)                           |
| `versions[].versionId` | `string \| null` | ID of the version                                          |
| `versions[].size`      | `number \| null` | Size (bytes)                                               |
| `versions[].createdAt` | `string \| null` | When the version was made (ISO 8601)                       |
| `versions[].isCurrent` | `boolean`        | Whether it is the current version                          |
| `hasMore`              | `boolean`        | Always false                                               |

#### Response Example

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

#### Error Responses

| Status | Description                                                                                                    |
| ------ | -------------------------------------------------------------------------------------------------------------- |
| `400`  | path is missing or empty (`code: "invalid_parameter"`)                                                         |
| `403`  | Missing chat:exec scope                                                                                        |
| `404`  | The file was not found, or it is not yours (`code: "not_found"`)                                               |
| `502`  | An internal temporary error occurred in the service (`code: "upstream_connection_error"`). Retry after a while |

## Common Rules for Agents, Playbooks, and Skills

These rules are common to the APIs that read, create, change, delete, and copy Agents, Playbooks, and Skills. They cannot be called with a system integration token (calling returns `403 Forbidden` (`forbidden`)).

| Operation     | Scope                                                                                 | Target                                                                                               | When out of scope                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Read          | `assets:read` (the lists of skills and playbooks can also be called with `chat:exec`) | Your own and published ones                                                                          | Another user's private ones and ones that do not exist return `404 Not Found` (`agent_not_found`, `playbook_not_found`, `skill_not_found`) |
| Create / copy | `assets:write`                                                                        | —                                                                                                    | —                                                                                                                                          |
| Update        | `assets:write`                                                                        | Your own only                                                                                        | Another user's returns `404 Not Found`                                                                                                     |
| Delete        | `assets:delete`                                                                       | Your own only (a system administrator can also delete playbooks and skills published by other users) | Another user's returns `404 Not Found`                                                                                                     |

- To change another user's resource, copy it to your own and change the copy.
- When changing, put the `digest` from the get API into `baseDigest` and send it. If another change was made after you got it, `409 Conflict` (`stale_base`) is returned. Get it again and resend.
- A JSON body can be up to 3 MiB. A larger body returns `413 Payload Too Large` (`body_too_large`). For the APIs that send skill files, see the limit in the description of each API.
- The Agent APIs return `403 Forbidden` (`sso_required`) for a token of a user who does not sign in with SSO.

Resends are handled as follows.

| API                                                      | What identifies a resend                | Resending with the same value                                                                                                                                                                                             |
| -------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create                                                   | —                                       | Another one is created. If the response did not arrive, check whether it was created by using the ID and `createdAt` in the list before sending again                                                                     |
| Copy                                                     | `Idempotency-Key` header (optional)     | The first copy is returned and no other is created. Without it, sending again creates another one, as with create (except copying a registered Agent in the Marketplace edition; see the description of copying an Agent) |
| Edit skill documents (`PATCH /v1/skills/:skillId/files`) | The `Idempotency-Key` header (optional) | Returns the version created by the first request without creating a new version                                                                                                                                           |

### Publishing Approval for Skills and Playbooks

When the tenant administrator requires approval to share skills and playbooks, sending `isShared: true` does not share it; it waits for publishing approval instead (the same as "Request publishing" on the screen). The administrator approves or returns it in the admin console. Whether approval is required cannot be read through the API. Check whether it was shared or is waiting for approval with `isShared` and `shareRequestStatus` in the response.

The following request status fields are included in the list and get responses of your own skills and playbooks, and in the responses of creating, changing, and copying them. They are not included in the shared lists or when getting an item shared by another user. However, `sharePendingListing` is not included in the `skill` of the response for editing skill documents (get the skill to read it).

| Field                   | Type             | Description                                                                                                                                                                                                       |
| ----------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shareRequestStatus`    | `string \| null` | "pending" (awaiting approval), "rejected" (returned), or null (not requested)                                                                                                                                     |
| `shareRequestNote`      | `string \| null` | Note for the request                                                                                                                                                                                              |
| `shareReviewNote`       | `string \| null` | Comment from the administrator (for example, when it was returned)                                                                                                                                                |
| `shareRequestedAt`      | `string \| null` | When it was requested (ISO 8601)                                                                                                                                                                                  |
| `sharePendingVersionId` | `string \| null` | Skills only. ID of the version awaiting approval                                                                                                                                                                  |
| `sharePendingListing`   | `object \| null` | Skills only. Category and tags awaiting approval. The fields recorded for the pending change (category, tags) are included, even when changed back to the shared values before approval. null when there are none |

- **Note for the request** (`shareRequestNote`): Can be sent when creating a skill, replacing the files of a skill, changing the settings of a skill, and creating or changing a playbook. Up to 2000 characters, not counting leading and trailing whitespace (a longer note returns `400 Bad Request` (`invalid_parameter`)). An empty string, whitespace only, or null is the same as not sending it. The note is kept only when a request is made. It is not used when no approval was needed (a tenant that does not require approval). You can tell which happened from `shareRequestStatus` and `isShared` in the response.
- **The note alone cannot be changed**: Sending a different note to an item awaiting approval without changing its content returns `400 Bad Request` (`invalid_parameter`). To change the note, withdraw the request and request again. The same note as now is accepted as a resend.
- **Withdrawing**: Send `isShared: false` to an item awaiting approval (with Change Skill Settings for a skill, and Change Playbook for a playbook).
- **New versions of a shared skill**: In a tenant where publishing approval is enabled, changing the files of a shared skill makes the new version wait for approval, and the previous version is used until it is approved.
- **Category and tags of a shared skill**: In a tenant where publishing approval is enabled, changing the category or tags of a shared skill (with Change Skill Settings) makes the new values wait for approval, and the skill's `category` and `tags` keep the previous values until it is approved. The values awaiting approval are in `sharePendingListing`. If `isShared: false` is sent in the same call, the change is applied at once without approval and the skill stops being shared.
- **Content of a shared playbook**: In a tenant where publishing approval is enabled, changing the content of a shared playbook (name, description, category, tags, and steps) keeps it shared (`isShared` stays `true`) and makes the changed content a request (`shareRequestStatus` is `"pending"`). Until it is approved, other users see the approved content (in the shared list, Get, and Copy). Your own Get, and your own Agents and chats, use the changed content. Changing it back to the shared content withdraws the request. After the request is sent back, sending `isShared: true` (even without changing the content) requests again.

## Agents

Agents that are placed on project steps and run are handled as library resources. An Agent ID (`agentId`) is a different value from the placement ID assigned when the Agent is placed in a project.

### Endpoints

| メソッド   | エンドポイント                    | 説明                                    | Scope (SaaS)    |
| ------ | -------------------------- | ------------------------------------- | --------------- |
| GET    | `/v1/agents`               | List your Agents                      | `assets:read`   |
| GET    | `/v1/agents/shared`        | List shared Agents                    | `assets:read`   |
| GET    | `/v1/agents/:agentId`      | Get an Agent                          | `assets:read`   |
| POST   | `/v1/agents`               | Create an Agent                       | `assets:write`  |
| PATCH  | `/v1/agents/:agentId`      | Edit an Agent                         | `assets:write`  |
| DELETE | `/v1/agents/:agentId`      | Delete an Agent                       | `assets:delete` |
| POST   | `/v1/agents/:agentId/copy` | Copy a shared Agent as your own Agent | `assets:write`  |

### GET`/v1/agents`

Lists your Agents in descending order of last update (newest first). Supports cursor-based pagination. The list of shared Agents (`GET /v1/agents/shared`) uses the same query parameters and response.

#### Query Parameters

| Parameter | Type      | Default | Description                                                             |
| --------- | --------- | ------- | ----------------------------------------------------------------------- |
| `q`       | `string`  | `—`     | Filter by part of the name, description, or goal (up to 100 characters) |
| `limit`   | `integer` | `50`    | Number of items per page (1-100)                                        |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)  |

#### Request Example

**List agents**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents?q=order&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": "order", "limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents" + "?q=order&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=order&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Fields (200 OK)

| Field     | Type      | Description                                                                               |
| --------- | --------- | ----------------------------------------------------------------------------------------- |
| `agents`  | `array`   | Array of Agent objects. Each item is the same as the Get Agent response except for digest |
| `hasMore` | `boolean` | Whether there is a next page                                                              |
| `cursor`  | `string`  | Cursor for the next page. Included only when hasMore is true                              |

#### Response Example

```json
{
  "agents": [
    {
      "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
      "name": "Order data import",
      "description": "Create order data from order emails",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "isShared": false,
      "shareScope": "all",
      "shareOrganizations": null,
      "runtimeKind": "autonomous",
      "marketplaceAgentId": null,
      "spec": {
        "goal": "Create an order data table from the order emails received.",
        "guardrail": "Do not send anything to external services.",
        "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
}
```

#### Error Responses

| Status | Description                                                                                                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid limit (out of 1–100 range), cursor, or q (not a string, or longer than 100 characters) (code is invalid\_parameter)                                                               |
| `403`  | The assets:read scope is missing (code is insufficient\_scope), called with a system integration token (code is forbidden), or the user does not sign in with SSO (code is sso\_required) |

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

Lists shared Agents (including those you shared yourself). An Agent shared only with organizations is listed only for users in those organizations. The query parameters, response, and errors are the same as for listing your own Agents.

#### Request Example

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

Gets an Agent. You can get your own Agents and shared Agents.

#### Path Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

| Field                        | Type              | Description                                                                                                                                                                                                                                        |
| ---------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`                    | `string`          | Agent ID (UUID)                                                                                                                                                                                                                                    |
| `name`                       | `string \| null`  | Name                                                                                                                                                                                                                                               |
| `description`                | `string \| null`  | Description                                                                                                                                                                                                                                        |
| `ownerUserId`                | `string \| null`  | User ID of the owner                                                                                                                                                                                                                               |
| `isShared`                   | `boolean \| null` | Whether the Agent is shared                                                                                                                                                                                                                        |
| `shareScope`                 | `string \| null`  | Who the Agent is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)                                                                                                                                               |
| `shareOrganizations`         | `array \| null`   | Array of the organization codes it is shared with. Used when shareScope is "organizations"                                                                                                                                                         |
| `runtimeKind`                | `string \| null`  | Kind of runtime. "autonomous", or "marketplace" for a registered Agent of the Marketplace edition                                                                                                                                                  |
| `marketplaceAgentId`         | `string \| null`  | ID of the registered Agent in the Marketplace edition. null otherwise                                                                                                                                                                              |
| `spec`                       | `object`          | Definition of the Agent                                                                                                                                                                                                                            |
| `spec.goal`                  | `string \| null`  | Goal (instructions)                                                                                                                                                                                                                                |
| `spec.guardrail`             | `string \| null`  | Guardrail                                                                                                                                                                                                                                          |
| `spec.skills`                | `array`           | Skills to use                                                                                                                                                                                                                                      |
| `spec.skills[].skillId`      | `string \| null`  | Skill ID                                                                                                                                                                                                                                           |
| `spec.skills[].name`         | `string \| null`  | Skill name                                                                                                                                                                                                                                         |
| `spec.skills[].versionId`    | `string \| null`  | ID of the pinned skill version. null if not pinned, in which case the version at that time is always used                                                                                                                                          |
| `spec.playbookId`            | `string \| null`  | ID of the playbook to use                                                                                                                                                                                                                          |
| `spec.inputFiles`            | `array`           | Input files                                                                                                                                                                                                                                        |
| `spec.inputFiles[].type`     | `string \| null`  | Kind of input file. "blob" for library files. An Agent created from a scheduled job may have "git" or "upload"                                                                                                                                     |
| `spec.inputFiles[].filepath` | `string \| null`  | File path. For "blob", the same form as the filepath from GET /v1/library. For "git" and "upload", the stored reference with a leading /, which is not a library path                                                                              |
| `spec.inputFiles[].filename` | `string \| null`  | File name                                                                                                                                                                                                                                          |
| `spec.agentLevel`            | `string \| null`  | "default" or "high\_performance"                                                                                                                                                                                                                   |
| `spec.orgId`                 | `string \| null`  | Code of the organization used at run time                                                                                                                                                                                                          |
| `spec.jobRole`               | `string \| null`  | Code of the job type used at run time                                                                                                                                                                                                              |
| `spec.agentConfig`           | `object \| null`  | Not used at present (even if it has a value, the value is not used)                                                                                                                                                                                |
| `spec.exposureConsent`       | `object \| null`  | Not used at present (even if it has a value, the value is not used)                                                                                                                                                                                |
| `projectCount`               | `number \| null`  | Number of projects where this Agent is placed (placements in deleted projects are not counted)                                                                                                                                                     |
| `copyCount`                  | `number \| null`  | Number of times it has been copied                                                                                                                                                                                                                 |
| `adminStop`                  | `object \| null`  | When an administrator has stopped the Agent: where it was stopped from, why, and when. null if it is not stopped. Returned by List and Get                                                                                                         |
| `adminStop.source`           | `string \| null`  | Where it was stopped from. "aster" (an AGENTIC STAR administrator), or a connected service: "agent365" or "aws"                                                                                                                                    |
| `adminStop.reasonCode`       | `string \| null`  | The kind of reason. "admin" (an administrator stopped it), "remote\_stopped" (it was stopped in the connected service), or "remote\_unreachable" (the connected service cannot be reached)                                                         |
| `adminStop.reason`           | `string \| null`  | The reason text. Present only for your own Agents (null for another user's Agent)                                                                                                                                                                  |
| `adminStop.stoppedAt`        | `string \| null`  | When it was stopped (ISO 8601)                                                                                                                                                                                                                     |
| `createdAt`                  | `string \| null`  | Creation time (ISO 8601)                                                                                                                                                                                                                           |
| `updatedAt`                  | `string \| null`  | Last update time (ISO 8601)                                                                                                                                                                                                                        |
| `digest`                     | `string`          | Value to send as baseDigest when editing the Agent. It is made from the name, description, sharing, sharing scope, organizations it is shared with, and definition, and does not change with the number of projects, the copy count, or timestamps |

#### Response Example

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "Order intake",
  "description": "Creates order data from order emails",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "Create an order table from the order emails received.",
    "guardrail": "Do not send anything to external services.",
    "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"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | agentId is not a UUID (code is invalid\_parameter)                                                                                                                                        |
| `403`  | The assets:read scope is missing (code is insufficient\_scope), called with a system integration token (code is forbidden), or the user does not sign in with SSO (code is sso\_required) |
| `404`  | The Agent does not exist, or it is another user's private Agent (code is agent\_not\_found)                                                                                               |

### POST`/v1/agents`

Creates an Agent.

#### Request Body

| Field             | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`            | `string`  | Yes      | Name (up to 255 characters; cannot be empty)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `description`     | `string`  | —        | Description (up to 5000 characters)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `isShared`        | `boolean` | —        | Whether to share it. Private if omitted                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `spec`            | `object`  | Yes      | Definition of the Agent                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `spec.goal`       | `string`  | Yes      | Goal (instructions). Up to 5000 characters. Cannot be only whitespace                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `spec.guardrail`  | `string`  | —        | Guardrail. Up to 5000 characters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `spec.skills`     | `array`   | —        | Skills to use, in the form \[{ skillId, versionId? }]: up to 10 of your own skills or shared skills (active ones). With versionId, that version is pinned; if omitted or null, the version at that time is always used. For a skill of another user, versionId must be a version that has been shared (the range returned by List Skill Versions). You can send the spec.skills from the get API as is (name is ignored). The same skill cannot be specified twice                                                             |
| `spec.playbookId` | `string`  | —        | ID of the playbook to use. Your own playbooks only                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `spec.inputFiles` | `array`   | —        | Input files, in the form \[{ type, filepath, filename? }]: up to 10. type is "blob" (a file in your library; filepath is the filepath from GET /v1/library). An Agent created from a scheduled job may have "git" or "upload", and the values from the get API can be sent as is. filepath cannot be empty after removing leading /. filename is a string of up to 255 characters, or null. At run time, the attached input files are passed as they are (they are not dropped even if they are not the project owner's files) |
| `spec.agentLevel` | `string`  | —        | "default" or "high\_performance"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `spec.orgId`      | `string`  | —        | Code of the organization used at run time (up to 255 characters)                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `spec.jobRole`    | `string`  | —        | Code of the job type used at run time (up to 255 characters)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

Sending `null` for `description` or for a field of `spec` other than `goal` is the same as omitting it (`spec.skills` and `spec.inputFiles` become empty).

`spec.skillIds` and `spec.skillVersions` are not accepted (sending them returns `400`, `invalid_parameter`). Specify skills with `spec.skills`.

#### Request Example

**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": "Order data import",
  "description": "Create order data from order emails",
  "spec": {
    "goal": "Create an order data table from the order emails received.",
    "guardrail": "Do not send anything to external services.",
    "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': 'Order data import', 'description': 'Create order data from order emails', 'spec': {'goal': 'Create an order data table from the order emails received.', 'guardrail': 'Do not send anything to external services.', '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": "Order data import", "description": "Create order data from order emails", "spec": {"goal": "Create an order data table from the order emails received.", "guardrail": "Do not send anything to external services.", "skills": [{"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"}], "agentLevel": "default"}}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "Order data import", "description": "Create order data from order emails", "spec": {"goal": "Create an order data table from the order emails received.", "guardrail": "Do not send anything to external services.", "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)
```

#### Response (201 Created)

Returns the created Agent in the same form as the Get Agent response (without `adminStop`; check it with List or Get), plus `removedSkillIds` (string\[]): the IDs of skills that could no longer be used (deleted, deactivated, no longer shared, or the pinned version does not exist or is not shared) and were removed when saving. Empty if none were removed.

#### Response Example

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "Order data import",
  "description": "Create order data from order emails",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "Create an order data table from the order emails received.",
    "guardrail": "Do not send anything to external services.",
    "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": []
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                                                                                                                                 |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | name or spec is missing, name, description, or isShared has the wrong type or length, name is only whitespace, spec is not an object, spec.playbookId is not a UUID, spec.skills has the wrong form (skillId or versionId is not a UUID, the same skill twice, and so on), or spec.skillIds or spec.skillVersions was sent  |
| `400`  | `invalid_spec`           | spec.goal is missing or only whitespace, a string field in spec has the wrong type or length, spec.agentLevel is not an allowed value, spec.inputFiles has the wrong form (type other than "blob", "git", or "upload", an empty filepath, a filename over 255 characters, and so on), or more than 10 skills or input files |
| `400`  | `playbook_not_found`     | spec.playbookId is not one of your playbooks                                                                                                                                                                                                                                                                                |
| `400`  | `skill_not_found`        | A skill in spec.skills is neither your own skill nor an active shared skill                                                                                                                                                                                                                                                 |
| `400`  | `version_not_found`      | A versionId in spec.skills is not a version of that skill, or is a version of another user's skill that is not shown (one not returned by List Skill Versions)                                                                                                                                                              |
| `400`  | `file_not_found`         | A file in spec.inputFiles whose type is "blob" is not in your library                                                                                                                                                                                                                                                       |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                             |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                                                                                                                                                                                           |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                                                                                                                                      |
| `403`  | `sso_required`           | The user does not sign in with SSO                                                                                                                                                                                                                                                                                          |
| `413`  | `body_too_large`         | The body exceeds 3 MiB                                                                                                                                                                                                                                                                                                      |
| `415`  | `unsupported_media_type` | The body Content-Type is not application/json                                                                                                                                                                                                                                                                               |

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

Edits one of your Agents. Only the fields you send are changed.

#### Path Parameters

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

#### Request Body

| Field                | Type      | Required | Description                                                                                                                                                                                                                                                                                                                |
| -------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`         | `string`  | Yes      | The digest from the Get Agent response                                                                                                                                                                                                                                                                                     |
| `name`               | `string`  | —        | Name (up to 255 characters; cannot be empty)                                                                                                                                                                                                                                                                               |
| `description`        | `string`  | —        | Description (up to 5000 characters; cannot be an empty string, only whitespace, or null)                                                                                                                                                                                                                                   |
| `isShared`           | `boolean` | —        | Whether to share it                                                                                                                                                                                                                                                                                                        |
| `shareScope`         | `string`  | —        | Who the Agent is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)                                                                                                                                                                                                                       |
| `shareOrganizations` | `array`   | —        | Organization codes it is shared with (up to 20, each up to 255 characters; surrounding whitespace is removed and duplicates are merged). Sending it replaces the whole list. At least one is required when the item is shared with the scope "organizations", and when it is sent together with shareScope "organizations" |
| `spec`               | `object`  | —        | Definition of the Agent. Only the fields you send are overlaid on the current definition (skills and inputFiles are replaced as whole arrays). The fields are the same as when creating an Agent. Sending null for a field removes it (skills and inputFiles become empty). goal cannot be removed                         |

Send at least one of name, description, isShared, shareScope, shareOrganizations, and spec.

When you change `spec`, the playbook and input files the definition points to, and the skills you newly add (including skills whose version you change), are checked, including fields you did not send. `400` is returned unless the playbook is your own, the skills are active and are your own or shared, and the input files are in your library. Skills the Agent already had are not refused with `400` even if they can no longer be used: they are removed when saving and returned in `removedSkillIds`. A copied Agent may point to another user's playbook, skills, or input files (a skill that is shared and active still points to the original skill after copying, and it can no longer be used once its sharing is stopped). In that case, change them to your own.

#### Request Example

**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": "Create an order data table from order emails"
}'
```

**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': 'Create an order data table from order emails'},
)

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": "Create an order data table from order emails"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs", "description": "Create an order data table from order emails"}`)
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)
```

#### Response (200 OK)

Returns the edited Agent (with a new `digest`) in the same form as the Get Agent response (without `adminStop`; check it with List or Get), plus `removedSkillIds` (string\[]): the IDs of skills that could no longer be used (deleted, deactivated, no longer shared, or the pinned version does not exist or is not shared) and were removed when saving. Empty if none were removed.

#### Response Example

```json
{
  "agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
  "name": "Order data import",
  "description": "Create an order data table from order emails",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "Create an order data table from the order emails received.",
    "guardrail": "Do not send anything to external services.",
    "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": []
}
```

#### Error Responses

| Status | code                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`            | agentId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name, description, or isShared has the wrong type or length, name is only whitespace, description was set to an empty string, only whitespace, or null, spec is not an object, spec.playbookId is not a UUID, spec.skills has the wrong form (the same skill twice, and so on), or spec.skillIds or spec.skillVersions was sent |
| `400`  | `invalid_spec`                 | spec.goal was set to null or only whitespace, a string field in spec has the wrong type or length, spec.agentLevel is not an allowed value, spec.inputFiles has the wrong form (type other than "blob", "git", or "upload", an empty filepath, a filename over 255 characters, and so on), or more than 10 skills or input files                                                                                           |
| `400`  | `playbook_not_found`           | The playbook in the definition is not one of your playbooks                                                                                                                                                                                                                                                                                                                                                                |
| `400`  | `skill_not_found`              | A skill you newly added (including a skill whose version you changed) is neither your own skill nor an active shared skill (skills the Agent already had are removed when saving and returned in removedSkillIds)                                                                                                                                                                                                          |
| `400`  | `version_not_found`            | The versionId of a skill you newly added or whose version you changed is not a version of that skill, or is a version of another user's skill that is not shown (one not returned by List Skill Versions). A pin kept without changing its version that can no longer be used is removed when saving and returned in removedSkillIds                                                                                       |
| `400`  | `file_not_found`               | An input file in the definition whose type is "blob" is not in your library                                                                                                                                                                                                                                                                                                                                                |
| `400`  | `runtime_not_allowed`          | A registered Agent of the Marketplace edition cannot be edited                                                                                                                                                                                                                                                                                                                                                             |
| `400`  | `invalid_share_scope`          | shareScope is not "all" or "organizations"                                                                                                                                                                                                                                                                                                                                                                                 |
| `400`  | `invalid_share_organizations`  | shareOrganizations is not an array, has 21 or more items, or has a value that is not a string, is empty or only whitespace, or is 256 characters or longer                                                                                                                                                                                                                                                                 |
| `400`  | `share_organizations_required` | "organizations" was sent for shareScope with an empty shareOrganizations, or the item is shared (isShared is true in the sent or current value) while the scope is "organizations" and there is no organization (the sent and current values are combined)                                                                                                                                                                 |
| `400`  | `invalid_body`                 | The body is malformed JSON or not a JSON object                                                                                                                                                                                                                                                                                                                                                                            |
| `403`  | `insufficient_scope`           | The assets:write scope is missing                                                                                                                                                                                                                                                                                                                                                                                          |
| `403`  | `forbidden`                    | Called with a system integration token                                                                                                                                                                                                                                                                                                                                                                                     |
| `403`  | `sso_required`                 | The user does not sign in with SSO                                                                                                                                                                                                                                                                                                                                                                                         |
| `404`  | `agent_not_found`              | The Agent does not exist, or it is another user's Agent                                                                                                                                                                                                                                                                                                                                                                    |
| `409`  | `stale_base`                   | The Agent has changed since you got it                                                                                                                                                                                                                                                                                                                                                                                     |
| `413`  | `body_too_large`               | The body exceeds 3 MiB                                                                                                                                                                                                                                                                                                                                                                                                     |
| `415`  | `unsupported_media_type`       | The body Content-Type is not application/json                                                                                                                                                                                                                                                                                                                                                                              |

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

Deletes one of your Agents. The deleted Agent is removed from the projects where it was placed, and the sweeps of those placements stop.

#### Path Parameters

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

#### Query Parameters

| Parameter | Type     | Default   | Description                                                                                                       |
| --------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `force`   | `string` | `"false"` | Specify "true" to delete even if the Agent is placed in projects. A value other than "true" / "false" returns 400 |

#### Request Example

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

#### Response (200 OK)

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

#### Error Responses

| Status | code                 | Description                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | agentId is not a UUID, or force is not "true" / "false"                                          |
| `403`  | `insufficient_scope` | The assets:delete scope is missing                                                               |
| `403`  | `forbidden`          | Called with a system integration token                                                           |
| `403`  | `sso_required`       | The user does not sign in with SSO                                                               |
| `404`  | `agent_not_found`    | The Agent does not exist, or it is another user's Agent                                          |
| `409`  | `agent_in_use`       | The Agent is placed in projects (with force=true, it is removed from the placements and deleted) |
| `409`  | `agent_running`      | A sweep of this Agent is running                                                                 |
| `409`  | `admin_stopped`      | An administrator has stopped this Agent                                                          |

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

Copies a shared Agent as your own Agent. A newly created copy is private. No body is required (a body is not read even if sent).

The definition is copied as is. The playbook, skills, and input files it points to are adjusted so that the user making the copy can use them, as follows.

- **Playbook**: If it is not your own, it is duplicated as your own playbook, and the copy points to the duplicate. In a tenant where publishing approval is enabled, a playbook that is not shared is removed instead of duplicated, and for a shared playbook the approved content is duplicated
- **Skills**: Your own skills and skills that are shared and active are kept as they are (if the source Agent specifies a version, that version is used; otherwise, the owner's current version is used). When a version of a shared skill is specified, only a version that has been shared is kept as it is. Other skills have the version in use duplicated as your own skill, and the copy points to the duplicate. In a tenant where publishing approval is enabled, a skill that is not shared or is inactive (including one pinned to a version that has never been shared) is removed instead of duplicated
- **Input files**: They are not duplicated. Those that are not in your library are removed
- Playbooks and skills that cannot be found are removed

If the definition cannot be adjusted this way (for example, when it points to one of your own skills that is inactive), the playbook, skills, and input files are all removed before copying. For a registered Agent of the Marketplace edition, if you already have your own Agent for the same registered Agent, that Agent is returned instead of creating a new one.

#### Path Parameters

| パラメータ     | 型        | 必須 | 説明                             |
| --------- | -------- | -- | ------------------------------ |
| `agentId` | `string` | 必須 | ID of the Agent to copy (UUID) |

#### Request Headers

| Header            | Required | Description                                                                                                                                                                                     |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | —        | A key to identify resends (8 to 128 characters of letters, digits, and \_ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |

#### Request Example

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

#### Response (201 Created)

Returns the Agent created by the copy in the same form as the Get Agent response (without `adminStop`; check it with List or Get), with the following three fields added. For a registered Agent of the Marketplace edition, your existing Agent may be returned (in that case, `projectCount` in the response is `0`; check the number of projects with the Get Agent API).

| Field                | Type       | Description                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `duplicated`         | `object`   | Numbers of items duplicated as your own (playbooks: number of playbooks, skills: number of skills)                                                                                                                                                                                                                                                   |
| `strippedInputFiles` | `string[]` | When input files were removed (including when the definition could not be adjusted and everything was removed), contains one item: the name of the copied Agent. Empty if nothing was removed. These are not the names of the removed files                                                                                                          |
| `strippedResources`  | `string[]` | In a tenant where publishing approval is enabled, when a playbook that is not shared, or a skill that is not shared or is inactive (including a pin to a version that has never been shared), was removed, contains one item: the name of the copied Agent. Empty if nothing was removed. These are not the names of the removed playbooks or skills |

If you resend with the same `Idempotency-Key`, `200 OK` is returned with the first copy in the same form. In that case, `duplicated` is 0, and `strippedInputFiles` and `strippedResources` are empty (a resend duplicates nothing new). If the first copy has been deleted, `404 Not Found` (`agent_not_found`) is returned; send the request with a new key.

#### Response Example

```json
{
  "agentId": "2c9d4e6f-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
  "name": "Order data import",
  "description": "Create order data from order emails",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "isShared": false,
  "shareScope": "all",
  "shareOrganizations": null,
  "runtimeKind": "autonomous",
  "marketplaceAgentId": null,
  "spec": {
    "goal": "Create an order data table from the order emails received.",
    "guardrail": "Do not send anything to external services.",
    "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": []
}
```

#### Error Responses

| Status | code                      | Description                                                                                                                                                        |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`       | agentId is not a UUID                                                                                                                                              |
| `400`  | `idempotency_key_invalid` | The format of Idempotency-Key is invalid                                                                                                                           |
| `403`  | `insufficient_scope`      | The assets:write scope is missing                                                                                                                                  |
| `403`  | `forbidden`               | Called with a system integration token                                                                                                                             |
| `403`  | `sso_required`            | The user does not sign in with SSO                                                                                                                                 |
| `404`  | `agent_not_found`         | The Agent does not exist, it is another user's private Agent, or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
| `409`  | `already_owned`           | You tried to copy your own Agent                                                                                                                                   |
| `409`  | `idempotency_conflict`    | A copy of a different Agent was sent with the same Idempotency-Key                                                                                                 |
| `409`  | `admin_stopped`           | An administrator has stopped this Agent                                                                                                                            |

## Skills

Reads, creates, edits, deletes, and copies skills. Use a `skillId` in the Chat `skillIds` parameter to load the skill into the agent, or in an Agent definition (`spec.skills`). For the common rules, see [Common Rules for Agents, Playbooks, and Skills](#assets-common).

A skill consists of `SKILL.md` and accompanying files (documents, scripts, setting files, and so on). Each time the files change, a new version is created, and earlier versions are kept.

Use `GET /v1/skills` for skills you registered yourself, and `GET /v1/skills/shared` for publicly shared skills (including those you shared yourself). Shared skills can be specified in `skillIds` directly without copying them.

### Endpoint List

| メソッド   | エンドポイント                             | 説明                                | Scope (SaaS)              |
| ------ | ----------------------------------- | --------------------------------- | ------------------------- |
| GET    | `/v1/skills`                        | List your skills                  | `chat:exec / assets:read` |
| GET    | `/v1/skills/shared`                 | List shared skills                | `chat:exec / assets:read` |
| GET    | `/v1/skills/:skillId`               | Get a skill                       | `assets:read`             |
| GET    | `/v1/skills/:skillId/versions`      | List the versions of a skill      | `assets:read`             |
| GET    | `/v1/skills/:skillId/files`         | List the files of a skill         | `assets:read`             |
| GET    | `/v1/skills/:skillId/files/content` | Get one file of a skill           | `assets:read`             |
| GET    | `/v1/skills/:skillId/download`      | Get the files of a skill as a zip | `assets:read`             |
| POST   | `/v1/skills`                        | Create a skill                    | `assets:write`            |
| PUT    | `/v1/skills/:skillId/files`         | Replace the files of a skill      | `assets:write`            |
| PATCH  | `/v1/skills/:skillId/files`         | Edit the documents of a skill     | `assets:write`            |
| PATCH  | `/v1/skills/:skillId`               | Change the settings of a skill    | `assets:write`            |
| DELETE | `/v1/skills/:skillId`               | Delete a skill                    | `assets:delete`           |
| POST   | `/v1/skills/:skillId/copy`          | Copy a skill as your own skill    | `assets:write`            |

### GET`/v1/skills`

Lists the skills you registered, ordered by last update time (newest first). Cursor-based pagination is supported.

#### Query Parameters

| Parameter     | Type      | Default | Description                                                                                      |
| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------ |
| `active_only` | `boolean` | `true`  | Set to false to also include deactivated skills. A value other than "true" / "false" returns 400 |
| `limit`       | `integer` | `50`    | Number of items per page (1-100)                                                                 |
| `cursor`      | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                           |

#### Request Example

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

#### Response Fields (200 OK)

| Field                         | Type             | Description                                                                                                                                                                                                  |
| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `skills`                      | `array`          | Array of skill objects                                                                                                                                                                                       |
| `skills[].skillId`            | `string`         | Skill ID (specify this in the Chat skillIds parameter)                                                                                                                                                       |
| `skills[].ownerUserId`        | `string \| null` | User ID of the owner                                                                                                                                                                                         |
| `skills[].name`               | `string`         | Skill name                                                                                                                                                                                                   |
| `skills[].description`        | `string?`        | Skill description                                                                                                                                                                                            |
| `skills[].category`           | `string?`        | Category                                                                                                                                                                                                     |
| `skills[].tags`               | `array`          | Array of tags (duplicates are returned once). An empty array when unset                                                                                                                                      |
| `skills[].isShared`           | `boolean`        | Whether you share the skill publicly                                                                                                                                                                         |
| `skills[].isActive`           | `boolean`        | Whether the skill is active                                                                                                                                                                                  |
| `skills[].shareRequestStatus` | `string \| null` | Status of the publishing request (see "Publishing Approval for Skills and Playbooks"). sharePendingVersionId, sharePendingListing, shareRequestNote, shareReviewNote, and shareRequestedAt are also included |
| `skills[].createdAt`          | `string`         | Creation time (ISO 8601)                                                                                                                                                                                     |
| `skills[].updatedAt`          | `string`         | Last update time (ISO 8601)                                                                                                                                                                                  |
| `hasMore`                     | `boolean`        | Whether a next page exists                                                                                                                                                                                   |
| `cursor`                      | `string`         | Cursor for the next page. Included only when hasMore is true                                                                                                                                                 |

#### Response Example

```json
{
  "skills": [
    {
      "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "name": "release-notes",
      "description": "Generate release notes",
      "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
}
```

#### Pagination

While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

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

# Second page (use the cursor returned by the first page)
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=50&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"
```

To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

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

#### Error Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `400`  | limit is not an integer between 1 and 100                    |
| `400`  | cursor is invalid (not a value from a previous response)     |
| `400`  | active\_only is not "true" / "false"                         |
| `403`  | Has neither chat:exec nor assets:read                        |
| `403`  | Called with a system integration token (`code: "forbidden"`) |

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

Lists publicly shared skills (including skills you shared yourself), ordered by creation time (newest first). Cursor-based pagination is supported.

#### Query Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

Shared skills are always active, so the `isShared` / `isActive` fields are not included. The request status fields are not included either.

| Field                  | Type             | Description                                                             |
| ---------------------- | ---------------- | ----------------------------------------------------------------------- |
| `skills`               | `array`          | Array of skill objects                                                  |
| `skills[].skillId`     | `string`         | Skill ID (specify this in the Chat skillIds parameter)                  |
| `skills[].ownerUserId` | `string \| null` | User ID of the owner                                                    |
| `skills[].name`        | `string`         | Skill name                                                              |
| `skills[].description` | `string?`        | Skill description                                                       |
| `skills[].category`    | `string?`        | Category                                                                |
| `skills[].tags`        | `array`          | Array of tags (duplicates are returned once). An empty array when unset |
| `skills[].createdAt`   | `string`         | Creation time (ISO 8601)                                                |
| `skills[].updatedAt`   | `string`         | Last update time (ISO 8601)                                             |
| `hasMore`              | `boolean`        | Whether a next page exists                                              |
| `cursor`               | `string`         | Cursor for the next page. Included only when hasMore is true            |

#### Response Example

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

#### Error Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `400`  | limit is not an integer between 1 and 100                    |
| `400`  | cursor is invalid (not a value from a previous response)     |
| `403`  | Has neither chat:exec nor assets:read                        |
| `403`  | Called with a system integration token (`code: "forbidden"`) |

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

Gets a skill. You can get your own skills and shared skills.

#### Path Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

The same fields as an item in the list of your skills, plus the following two. For a skill shared by another user, `isShared`, `isActive`, and the request status fields are not included, as in the shared list.

| Field              | Type             | Description                                                                                                                                                                         |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currentVersionId` | `string \| null` | ID of the current version. null for a skill that was created before versions were recorded and whose files have not been changed since                                              |
| `digest`           | `string`         | The value to send as baseDigest when changing the skill settings. It is made from the shared setting, active setting, category, and tags, and does not change when the files change |

#### Response Example

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "Generates release notes",
  "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"
}
```

#### Error Responses

| Status | code                 | Description                                                     |
| ------ | -------------------- | --------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | skillId is not a UUID                                           |
| `403`  | `insufficient_scope` | The assets:read scope is missing                                |
| `403`  | `forbidden`          | Called with a system integration token                          |
| `404`  | `skill_not_found`    | The skill does not exist, or it is another user's private skill |

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

Lists the versions of a skill. Each time the files of a skill change, a new version is created, and earlier versions are kept. Up to 100 versions are returned, newest first. Pagination is not supported (`hasMore` is always `false`, and versions older than the latest 100 are not returned). If you know the ID of a version older than the latest 100, you can still get its file list and read its non-binary documents and its non-document text files of up to 200 KiB with the single-file API (to read all its files, copy the skill with that version).

For another user's shared skill, only the versions shared while it was shared are returned. Versions awaiting approval or sent back, and versions made while it was not shared, are not returned. For a skill whose sharing an administrator stopped, after it is shared again only the version at the time it was shared again and the versions shared after that are returned (versions from before the stop are not returned). Specifying a version that is not returned gives `400 Bad Request` (`version_not_found`).

#### Path Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

| Field                        | Type             | Description                                                                                                                                                                                                                                                                                   |
| ---------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skillId`                    | `string`         | Skill ID                                                                                                                                                                                                                                                                                      |
| `currentVersionId`           | `string \| null` | ID of the current version                                                                                                                                                                                                                                                                     |
| `versions`                   | `array`          | Array of versions (newest first)                                                                                                                                                                                                                                                              |
| `versions[].versionId`       | `string \| null` | Version ID                                                                                                                                                                                                                                                                                    |
| `versions[].versionNo`       | `number`         | Version number (starting from 1)                                                                                                                                                                                                                                                              |
| `versions[].parentVersionId` | `string \| null` | ID of the version this version was based on                                                                                                                                                                                                                                                   |
| `versions[].source`          | `string`         | How the version was created: "upload" (created or replaced by sending files), "edit" (documents were edited), "copy" (created by a copy), "baseline" (content from before versions were recorded), or "listing" (created to wait for approval of a category or tags change on a shared skill) |
| `versions[].contentDigest`   | `string \| null` | A value made from the contents of the files of the version. Versions with the same contents have the same value                                                                                                                                                                               |
| `versions[].createdAt`       | `string`         | When the version was created (ISO 8601)                                                                                                                                                                                                                                                       |
| `versions[].isCurrent`       | `boolean`        | Whether this is the current version                                                                                                                                                                                                                                                           |
| `hasMore`                    | `boolean`        | Always false                                                                                                                                                                                                                                                                                  |

For a skill that was created before versions were recorded and whose files have not been changed since, one item is returned with `versionId` and `contentDigest` set to `null` and `source` set to `"baseline"`.

#### Response Example

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

#### Error Responses

| Status | code                 | Description                                                     |
| ------ | -------------------- | --------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | skillId is not a UUID                                           |
| `403`  | `insufficient_scope` | The assets:read scope is missing                                |
| `403`  | `forbidden`          | Called with a system integration token                          |
| `404`  | `skill_not_found`    | The skill does not exist, or it is another user's private skill |

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

Lists the files of a version of a skill. File contents are not returned (read them with the single-file API).

#### Path Parameters

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

#### Query Parameters

| Parameter    | Type     | Default         | Description                                                                                                                                                                                                 |
| ------------ | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version_id` | `string` | Current version | ID of the version to read (UUID). The earlier name versionId is also accepted. If omitted and the owner reads a skill that has a version awaiting approval or returned for publishing, that version is read |

#### Request Example

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

#### Response Fields (200 OK)

| Field              | Type             | Description                                                                                                                                                                                                                                                |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skillId`          | `string`         | Skill ID                                                                                                                                                                                                                                                   |
| `versionId`        | `string \| null` | Version ID                                                                                                                                                                                                                                                 |
| `isCurrent`        | `boolean`        | Whether this is the current version                                                                                                                                                                                                                        |
| `digest`           | `string`         | The value to send as baseDigest when replacing the files of the skill or editing its documents (send the value from the file list read without version\_id)                                                                                                |
| `editable`         | `boolean`        | Whether the documents can be edited. true when it is your own skill and it contains no scripts or executables (.exe, .bin, .so, .dylib, .dll)                                                                                                              |
| `files`            | `array`          | Array of files (in path order)                                                                                                                                                                                                                             |
| `files[].path`     | `string`         | Path within the skill (for example, scripts/run.py)                                                                                                                                                                                                        |
| `files[].kind`     | `string`         | Kind of the file (decided by the extension): "document" (.md, .json, .yaml, .yml), "script" (.py, .js, .mjs, .cjs, .ts, .sh, .bash, .zsh, .rb, .pl, .php, .go, .rs, .java, .ps1, .bat, .cmd), or "other" (anything else, such as setting files and images) |
| `files[].size`     | `number`         | Size (bytes)                                                                                                                                                                                                                                               |
| `files[].editable` | `boolean`        | Whether the file is in a form whose contents can be changed by editing documents (true for a document that is not binary)                                                                                                                                  |
| `hasMore`          | `boolean`        | Always false (all items are returned)                                                                                                                                                                                                                      |

#### Response Example

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

#### Error Responses

| Status | code                 | Description                                                                              |
| ------ | -------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | skillId or version\_id is not a UUID, or version\_id and versionId have different values |
| `400`  | `version_not_found`  | version\_id is not a version of the skill                                                |
| `403`  | `insufficient_scope` | The assets:read scope is missing                                                         |
| `403`  | `forbidden`          | Called with a system integration token                                                   |
| `404`  | `skill_not_found`    | The skill does not exist, or it is another user's private skill                          |

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

Gets the contents of one file of a skill. The contents are always returned in full.

In an earlier version, documents (`kind` is `"document"` and the file is not binary; returned in full regardless of size) and text files of up to 200 KiB can be read. The same applies to the published version when the owner has a version awaiting approval or returned for publishing (if you omit the version, all the files of that version can be read). Binary files (including documents) and non-document files larger than 200 KiB in these versions return `400` (`version_not_readable`). To read all the files of an earlier version, copy the skill with `versionId` (`POST /v1/skills/:skillId/copy`), and then download the copied skill (`GET /v1/skills/:skillId/download`).

#### Path Parameters

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

#### Query Parameters

| Parameter    | Type     | Default         | Description                                                                                                                                                                                                 |
| ------------ | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`       | `string` | —               | Required. Path of the file (files\[].path in the file list; for example, scripts/run.py)                                                                                                                    |
| `version_id` | `string` | Current version | ID of the version to read (UUID). The earlier name versionId is also accepted. If omitted and the owner reads a skill that has a version awaiting approval or returned for publishing, that version is read |

#### Request Example

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

#### Response Fields (200 OK)

| Field       | Type             | Description                                                                                                               |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `skillId`   | `string`         | Skill ID                                                                                                                  |
| `versionId` | `string \| null` | Version ID                                                                                                                |
| `path`      | `string`         | Path of the file                                                                                                          |
| `kind`      | `string`         | Kind of the file (same as files\[].kind in the file list)                                                                 |
| `size`      | `number`         | Size (bytes)                                                                                                              |
| `encoding`  | `string`         | How the contents are represented: "utf-8" for a text file, or "base64" for a binary file (one whose contents include NUL) |
| `content`   | `string`         | Contents of the file (in full)                                                                                            |

#### Response Example

```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: Generate release notes\n---\n\n# Steps\n"
}
```

#### Error Responses

| Status | code                   | Description                                                                                                                                                                                                                   |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`    | skillId or version\_id is not a UUID, version\_id and versionId have different values, or path is missing                                                                                                                     |
| `400`  | `file_not_found`       | The file at path is not in the version                                                                                                                                                                                        |
| `400`  | `version_not_found`    | version\_id is not a version of the skill                                                                                                                                                                                     |
| `400`  | `version_not_readable` | A binary file (including a document) or a non-document file larger than 200 KiB was specified in an earlier version (or, when the owner has a version awaiting approval or returned for publishing, in the published version) |
| `403`  | `insufficient_scope`   | The assets:read scope is missing                                                                                                                                                                                              |
| `403`  | `forbidden`            | Called with a system integration token                                                                                                                                                                                        |
| `404`  | `skill_not_found`      | The skill does not exist, or it is another user's private skill                                                                                                                                                               |

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

Gets all the files (including setting files and images) of the current version of a skill (when the owner downloads a skill that has a version awaiting approval or returned for publishing, that version) as a zip. You cannot specify a version.

- The `Content-Type` of the response is `application/zip`. The file name (`Content-Disposition`) is based on the name of the skill (with the `.zip` extension).
- The zip has no top-level folder. You can send it as is to create a skill (`POST /v1/skills`) or to replace the files of a skill (`PUT /v1/skills/:skillId/files`).

#### Path Parameters

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

#### Error Responses

| Status | code                 | Description                                                     |
| ------ | -------------------- | --------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | skillId is not a UUID                                           |
| `403`  | `insufficient_scope` | The assets:read scope is missing                                |
| `403`  | `forbidden`          | Called with a system integration token                          |
| `404`  | `skill_not_found`    | The skill does not exist, or it is another user's private skill |

#### Request Example

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

Creates a skill. Send the request as `multipart/form-data`. The name and description are read from `name` and `description` in the YAML at the top of `SKILL.md` (the part enclosed in `---`).

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

| Field              | Type     | Required | Description                                                                                                                                                                                                                                                                          |
| ------------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `files`            | `file`   | Yes      | Files of the skill. Send one zip, or a set of files that includes SKILL.md. For a set of files, send one file per field, and set the file name to the path within the skill (for example, scripts/run.py). If you send only one file with the .md extension, it is saved as SKILL.md |
| `category`         | `string` | —        | Category (up to 40 characters, not counting leading and trailing whitespace)                                                                                                                                                                                                         |
| `tags`             | `string` | —        | Tags. Send one tag per field and repeat the field (up to 10 tags of 1 to 24 characters, not counting leading and trailing whitespace or a leading #). Tags are saved in lowercase without a leading #. Tags that become the same this way cannot be sent                             |
| `isShared`         | `string` | —        | Whether to share it ("true" or "false"). Private if omitted                                                                                                                                                                                                                          |
| `isActive`         | `string` | —        | Whether it is active ("true" or "false"). Active if omitted. A shared skill must be active                                                                                                                                                                                           |
| `shareRequestNote` | `string` | —        | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks")                                                                                                                            |

Rules for the files of a skill:

- `SKILL.md` is required at the root. The YAML at the top of `SKILL.md` must have `name` (up to 100 characters). `description` is optional (in the description shown in lists and elsewhere, the part over 1024 characters is cut off; `SKILL.md` itself is kept as is).
- If the contents of a zip are all in one folder, the folder is removed when saving. Files created by operating systems (`__MACOSX/`, files starting with `._`, `.DS_Store`, `Thumbs.db`, `desktop.ini`) are not saved.
- 1 to 50 files, up to 2 MiB per file, and up to 5 MiB in total after extraction.
- Keep the total size of the files you send (including the size after a set of files is packed) under 6 MiB.
- The contents go through a safety check.

#### Request Example

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

#### Response (201 Created)

Returns the created skill in the same form as the response for getting your own skill.

#### Response Example

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "Generate release notes",
  "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"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                            |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`      | files is missing, two files with the same path were sent, a file was sent in a field other than files, there are too many or too long form fields, or category, tags, isShared, or isActive is invalid |
| `400`  | `file_count`             | No files (for example, an empty zip) or more than 50 files                                                                                                                                             |
| `400`  | `file_too_large`         | A file exceeds 2 MiB                                                                                                                                                                                   |
| `400`  | `total_too_large`        | The total after extraction exceeds 5 MiB                                                                                                                                                               |
| `400`  | `zip_invalid`            | The zip cannot be extracted                                                                                                                                                                            |
| `400`  | `bad_path`               | A file path is invalid (for example, it contains ..)                                                                                                                                                   |
| `400`  | `skill_md_missing`       | SKILL.md is not at the root                                                                                                                                                                            |
| `400`  | `frontmatter_missing`    | SKILL.md does not start with YAML (the part enclosed in ---)                                                                                                                                           |
| `400`  | `name_missing`           | The YAML in SKILL.md has no name                                                                                                                                                                       |
| `400`  | `name_too_long`          | The name in SKILL.md exceeds 100 characters                                                                                                                                                            |
| `400`  | `shared_requires_active` | Tried to share the skill while it is inactive                                                                                                                                                          |
| `400`  | `guardrail_blocked`      | The contents were blocked by the safety check                                                                                                                                                          |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                                                                      |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                 |
| `413`  | `body_too_large`         | The total size of the files sent exceeds the limit                                                                                                                                                     |
| `415`  | `unsupported_media_type` | The Content-Type is not multipart/form-data                                                                                                                                                            |
| `502`  | `blob_write_failed`      | The files could not be saved (resend the request)                                                                                                                                                      |
| `503`  | `guardrail_unavailable`  | The safety check is not available (resend the request later)                                                                                                                                           |

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

Replaces all the files of one of your skills with the files you send. A new version is created, and earlier versions are kept. Files you do not send are not included in the new version. Send the request as `multipart/form-data`.

- The name and description are read again from the new `SKILL.md`.
- Agents and schedules that use this skill without fixing a version start using the new version (those that fix a version do not change). For a shared skill in a tenant where publishing approval is enabled, the previous version stays in use until the new version is approved.
- If you resend the request, `409 Conflict` (`stale_base`) is returned because the first request changed the version. Get the file list again and check whether the files were changed.

#### Path Parameters

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

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

| Field              | Type     | Required | Description                                                                                                                                               |
| ------------------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`       | `string` | Yes      | The digest from the file list read without version\_id                                                                                                    |
| `files`            | `file`   | Yes      | Files of the skill. How to send them and the rules are the same as when creating a skill                                                                  |
| `shareRequestNote` | `string` | —        | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |

The category, tags, shared setting, and active setting are not accepted (they are not read even if sent). Change them by changing the settings of the skill (`PATCH /v1/skills/:skillId`).

In a tenant where publishing approval is enabled, changing the content of a skill awaiting approval keeps it awaiting approval, with the changed content. If you change the content of a skill awaiting approval after the administrator stops requiring approval, the change shares it. This is the same as changing it on the screen (see [Publishing Approval](#assets-share-approval)).

`baseDigest` is checked before checking whether you may change the skill. For this reason, for a skill shared by another user, `409 Conflict` is returned if `baseDigest` does not match, and `404 Not Found` is returned if it matches.

#### Request Example

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

#### Response (200 OK)

Returns the skill after the replacement (with a new `currentVersionId`) in the same form as the response for getting your own skill. For a shared skill in a tenant where publishing approval is enabled, `currentVersionId` does not change and the ID of the new version is in `sharePendingVersionId`. Get the `digest` of the new version from the file list.

#### Response Example

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "Generate release notes",
  "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"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                    |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`      | skillId is not a UUID, baseDigest is missing, empty, or not a string, files is missing, two files with the same path were sent, or a file was sent in a field other than files |
| `400`  | `file_count`             | No files (for example, an empty zip) or more than 50 files                                                                                                                     |
| `400`  | `file_too_large`         | A file exceeds 2 MiB                                                                                                                                                           |
| `400`  | `total_too_large`        | The total after extraction exceeds 5 MiB                                                                                                                                       |
| `400`  | `zip_invalid`            | The zip cannot be extracted                                                                                                                                                    |
| `400`  | `bad_path`               | A file path is invalid (for example, it contains ..)                                                                                                                           |
| `400`  | `skill_md_missing`       | SKILL.md is not at the root                                                                                                                                                    |
| `400`  | `frontmatter_missing`    | SKILL.md does not start with YAML (the part enclosed in ---)                                                                                                                   |
| `400`  | `name_missing`           | The YAML in SKILL.md has no name                                                                                                                                               |
| `400`  | `name_too_long`          | The name in SKILL.md exceeds 100 characters                                                                                                                                    |
| `400`  | `guardrail_blocked`      | The contents were blocked by the safety check                                                                                                                                  |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                                              |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                         |
| `404`  | `skill_not_found`        | The skill does not exist, or it is another user's skill                                                                                                                        |
| `409`  | `stale_base`             | The files of the skill have changed since you got the file list                                                                                                                |
| `413`  | `body_too_large`         | The total size of the files sent exceeds the limit                                                                                                                             |
| `415`  | `unsupported_media_type` | The Content-Type is not multipart/form-data                                                                                                                                    |
| `502`  | `blob_write_failed`      | The files could not be saved                                                                                                                                                   |
| `503`  | `guardrail_unavailable`  | The safety check is not available (resend the request later)                                                                                                                   |

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

Edits the documents (`.md`, `.json`, `.yaml`, `.yml`) of one of your skills. A new version is created in which only the documents you send are changed; files you do not send are carried over from the current version (or, if there is a version awaiting approval or returned for publishing, from that version). Earlier versions are kept.

- You can add, rewrite, and delete documents. Files that are not documents cannot be changed. A skill that contains scripts or executables cannot be edited (fix it by replacing the files with `PUT /v1/skills/:skillId/files`).
- `SKILL.md` cannot be deleted. When `SKILL.md` is rewritten, the name and description are read again.
- The syntax of JSON and YAML documents is checked. After the edit, the skill must still have up to 50 files, up to 2 MiB per file, and up to 5 MiB in total. Edited documents go through a safety check.
- Agents and schedules that use this skill without fixing a version start using the new version (those that fix a version do not change). For a shared skill in a tenant where publishing approval is enabled, the previous version stays in use until the new version is approved.
- A note for the publishing request (`shareRequestNote`) cannot be sent (sending it returns `400 Bad Request` (`invalid_parameter`)). To attach a note, send it with Replace Skill Files (`PUT /v1/skills/:skillId/files`). In a tenant where publishing approval is enabled, fixing the version awaiting approval of a shared skill with this API keeps the note for the request.

#### Path Parameters

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

#### Request Headers

| Header            | Required | Description                                                                                                                                                                                            |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | —        | A key to identify resends (8 to 128 characters of letters, digits, and \_ . : -). If you resend with the same key, the version created by the first request is returned without creating a new version |

#### Request Body

| Field               | Type      | Required | Description                                                                                                    |
| ------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `baseDigest`        | `string`  | Yes      | The digest from the file list read without version\_id                                                         |
| `changes`           | `array`   | Yes      | Documents to change (1 to 50; each path only once)                                                             |
| `changes[].path`    | `string`  | Yes      | Path of the document (for example, SKILL.md or templates/notes.md). A path that does not exist adds a document |
| `changes[].content` | `string`  | —        | New contents of the document (in full). Omit it when deleting                                                  |
| `changes[].deleted` | `boolean` | —        | true deletes the document (true or false; other values cannot be sent)                                         |

```json
{
  "baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
  "changes": [
    { "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: Generates release notes\n---\n\n# Steps\n..." },
    { "path": "templates/old.md", "deleted": true }
  ]
}
```

#### Request Example

**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: Generate release notes\n---\n\n# Steps\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: Generate release notes\n---\n\n# Steps\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: Generate release notes\n---\n\n# Steps\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: Generate release notes\n---\n\n# Steps\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)
```

#### Response (201 Created)

| Field     | Type     | Description                                                                                                                                                    |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skill`   | `object` | The skill after the edit (same form as the response for getting your own skill, except that sharePendingListing is not included; read it by getting the skill) |
| `version` | `object` | The created version (same form as an item of versions\[] in the version list)                                                                                  |

If you resend with the same `Idempotency-Key`, `200 OK` is returned with the version created by the first request (`version`) and the current skill (`skill`). Sending a different edit with the same key returns `409 Conflict` (`command_conflict`). Resending before the first request finishes may return `409 Conflict` (`stale_base`); resend with the same key after it finishes.

#### Response Example

```json
{
  "skill": {
    "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
    "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
    "name": "release-notes",
    "description": "Generate release notes",
    "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
  }
}
```

#### Error Responses

| Status | code                      | Description                                                                                                                                 |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`       | skillId is not a UUID, baseDigest is missing, empty, or not a string, changes\[].deleted is not true or false, or shareRequestNote was sent |
| `400`  | `idempotency_key_invalid` | The format of Idempotency-Key is invalid                                                                                                    |
| `400`  | `invalid_body`            | The body is malformed JSON or not a JSON object                                                                                             |
| `400`  | `no_changes`              | changes is missing or empty, or has more than 50 items                                                                                      |
| `400`  | `bad_change`              | An item of changes has the wrong form (path is missing, content is not a string, and so on), or the same path was specified twice           |
| `400`  | `bad_path`                | path is invalid (for example, it contains ..)                                                                                               |
| `400`  | `not_editable`            | A file that is not a document was specified                                                                                                 |
| `400`  | `code_skill_not_editable` | The skill contains scripts or executables                                                                                                   |
| `400`  | `skill_md_required`       | Tried to delete SKILL.md                                                                                                                    |
| `400`  | `file_too_large`          | A file exceeds 2 MiB                                                                                                                        |
| `400`  | `invalid_syntax`          | A JSON or YAML document has a syntax error                                                                                                  |
| `400`  | `skill_too_large`         | After the edit, the skill exceeds 50 files or 5 MiB in total                                                                                |
| `400`  | `frontmatter_missing`     | SKILL.md does not start with YAML (the part enclosed in ---)                                                                                |
| `400`  | `name_missing`            | The YAML in SKILL.md has no name                                                                                                            |
| `400`  | `name_too_long`           | The name in SKILL.md exceeds 100 characters                                                                                                 |
| `400`  | `guardrail_blocked`       | The contents were blocked by the safety check                                                                                               |
| `403`  | `insufficient_scope`      | The assets:write scope is missing                                                                                                           |
| `403`  | `forbidden`               | Called with a system integration token                                                                                                      |
| `404`  | `skill_not_found`         | The skill does not exist, or it is another user's skill                                                                                     |
| `409`  | `stale_base`              | The files of the skill have changed since you got the file list (including an unreadable baseDigest)                                        |
| `409`  | `command_conflict`        | A different edit was sent with the same Idempotency-Key                                                                                     |
| `413`  | `body_too_large`          | The body exceeds 3 MiB                                                                                                                      |
| `415`  | `unsupported_media_type`  | The Content-Type of the body is not application/json                                                                                        |
| `502`  | `blob_write_failed`       | The files could not be saved                                                                                                                |
| `503`  | `guardrail_unavailable`   | The safety check is not available (resend the request later)                                                                                |

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

Changes the settings of one of your skills (shared setting, active setting, category, and tags). Only the fields you send are changed. The name and description are read from `SKILL.md`, so they cannot be changed here.

#### Path Parameters

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

#### Request Body

| Field              | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`       | `string`         | Yes      | The digest from the Get Skill response                                                                                                                                                                                                                                                                                                                                                                                                         |
| `isShared`         | `boolean`        | —        | Whether to share it. In a tenant where publishing approval is enabled, true makes it wait for approval, and sending false to an item awaiting approval withdraws the request                                                                                                                                                                                                                                                                   |
| `isActive`         | `boolean`        | —        | Whether it is active                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `category`         | `string \| null` | —        | Category (up to 40 characters, not counting leading and trailing whitespace). Send null or an empty string to clear it. For a shared skill in a tenant where publishing approval is enabled, the change waits for approval unless isShared false is sent in the same call (see "Publishing Approval for Skills and Playbooks")                                                                                                                 |
| `tags`             | `array`          | —        | Tags (up to 10 strings of 1 to 24 characters, not counting leading and trailing whitespace or a leading #). Send \[] to clear them. Tags are saved in lowercase without a leading #. Tags that become the same this way cannot be sent. For a shared skill in a tenant where publishing approval is enabled, the change waits for approval unless isShared false is sent in the same call (see "Publishing Approval for Skills and Playbooks") |
| `shareRequestNote` | `string \| null` | —        | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks")                                                                                                                                                                                                                                                                                      |

Send at least one field besides baseDigest (shareRequestNote does not count). You can also send a note for the publishing request (`shareRequestNote`; see [Publishing Approval](#assets-share-approval)). A change that would leave the skill shared but inactive returns `400` (`shared_requires_active`).

`baseDigest` is checked before checking whether you may change the skill. For this reason, for a skill shared by another user, `409 Conflict` is returned if `baseDigest` does not match, and `404 Not Found` is returned if it matches.

#### Request Example

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

#### Response (200 OK)

Returns the changed skill (with its current `digest`) in the same form as the response for getting your own skill. When you change the category or tags of a shared skill in a tenant where publishing approval is enabled (without sending `isShared: false` in the same call), `category` and `tags` keep the previous values, and the new values are in `sharePendingListing` (`shareRequestStatus` is `"pending"`). Changing only the category or tags does not change the `digest`.

#### Response Example

```json
{
  "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "Generate release notes",
  "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"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                          |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | skillId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, or a field has the wrong type, length, or number of items |
| `400`  | `shared_requires_active` | After the change, the skill would be shared but inactive                                                                                             |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                      |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                    |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                               |
| `404`  | `skill_not_found`        | The skill does not exist, or it is another user's skill                                                                                              |
| `409`  | `stale_base`             | The settings of the skill have changed since you got it                                                                                              |
| `413`  | `body_too_large`         | The body exceeds 3 MiB                                                                                                                               |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                 |

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

Deletes one of your skills together with the files of all its versions. A system administrator can also delete skills shared by other users.

#### Path Parameters

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

#### Query Parameters

| Parameter | Type     | Default   | Description                                                                                                           |
| --------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `force`   | `string` | `"false"` | Set to "true" to delete the skill even if schedules or Agents use it. A value other than "true" / "false" returns 400 |

- **When the skill is in use**: If schedules use this skill or Agents have it in their definitions, `409 Conflict` (`skill_referenced`; the numbers of schedules and Agents are in `error.message`) is returned. The schedules of all users are counted, whether active or inactive. Agents are counted regardless of their owners. Project jobs (sweeps of Agents placed in projects, and project executions that have not started yet) are not counted as schedules.
- **With `force=true`**: The skill is removed from the schedules that use it (including other users' schedules; the schedules themselves are kept) and from the definitions of all users' Agents, and then deleted. The sweeps of those Agents keep running with the definitions after the removal.

#### Request Example

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

#### Response (200 OK)

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

#### Error Responses

| Status | code                 | Description                                                                    |
| ------ | -------------------- | ------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`  | skillId is not a UUID, or force is not "true" / "false"                        |
| `403`  | `insufficient_scope` | The assets:delete scope is missing                                             |
| `403`  | `forbidden`          | Called with a system integration token                                         |
| `404`  | `skill_not_found`    | The skill does not exist, or it is another user's skill that you cannot delete |
| `409`  | `skill_referenced`   | Schedules or Agents use the skill (it can be deleted with force=true)          |

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

Copies one of your skills or a shared skill as a new skill of your own. All the files of the specified version (the current version if omitted; when the owner copies a skill that has a version awaiting approval or returned for publishing, that version) are copied, and the copy is created as private and active. The name, description, category, and tags are copied from the current values of the source. The versions of the copied skill start from 1.

The body is optional. To specify a version, send it as JSON.

#### Path Parameters

| パラメータ     | 型        | 必須 | 説明                             |
| --------- | -------- | -- | ------------------------------ |
| `skillId` | `string` | 必須 | ID of the skill to copy (UUID) |

#### Request Headers

| Header            | Required | Description                                                                                                                                                                                     |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | —        | A key to identify resends (8 to 128 characters of letters, digits, and \_ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |

#### Request Body

| Field       | Type     | Required | Description                                                                                                                                                                    |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `versionId` | `string` | —        | ID of the version to copy (UUID). The current version if omitted (when the owner copies a skill that has a version awaiting approval or returned for publishing, that version) |

#### Request Example

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

#### Response (201 Created)

Returns the skill created by the copy in the same form as the response for getting your own skill.

If you resend with the same `Idempotency-Key`, `200 OK` is returned with the first copy (its current contents) in the same form. If you omit `versionId` in the resend, the first copy is returned regardless of which version was copied the first time. If the first copy has been deleted, `404 Not Found` (`skill_not_found`) is returned; send the request with a new key.

#### Response Example

```json
{
  "skillId": "9e1f3a5b-7c2d-4e6f-8a0b-1c3d5e7f9a2b",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "name": "release-notes",
  "description": "Generate release notes",
  "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"
}
```

#### Error Responses

| Status | code                      | Description                                                                                                                                                        |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`       | skillId or versionId is not a UUID                                                                                                                                 |
| `400`  | `idempotency_key_invalid` | The format of Idempotency-Key is invalid                                                                                                                           |
| `400`  | `version_not_found`       | versionId is not a version of the skill                                                                                                                            |
| `400`  | `invalid_body`            | The body is malformed JSON or not a JSON object                                                                                                                    |
| `403`  | `insufficient_scope`      | The assets:write scope is missing                                                                                                                                  |
| `403`  | `forbidden`               | Called with a system integration token                                                                                                                             |
| `404`  | `skill_not_found`         | The skill does not exist, it is another user's private skill, or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
| `409`  | `idempotency_conflict`    | A copy of a different skill, or a copy with a versionId different from the first request, was sent with the same Idempotency-Key                                   |
| `413`  | `body_too_large`          | The body exceeds 3 MiB                                                                                                                                             |
| `415`  | `unsupported_media_type`  | The Content-Type of the body is not application/json                                                                                                               |
| `502`  | `blob_write_failed`       | The files could not be saved                                                                                                                                       |

## Playbooks

Reads, creates, edits, deletes, and copies playbooks. Use a `playbookId` in the Chat `playbookId` parameter to run the agent with a predefined procedure, or in an Agent definition (`spec.playbookId`). For the common rules, see [Common Rules for Agents, Playbooks, and Skills](#assets-common).

### Endpoint List

| メソッド   | エンドポイント                          | 説明                                          | Scope (SaaS)              |
| ------ | -------------------------------- | ------------------------------------------- | ------------------------- |
| GET    | `/v1/playbooks`                  | List your playbooks                         | `chat:exec / assets:read` |
| GET    | `/v1/playbooks/shared`           | List shared playbooks                       | `chat:exec / assets:read` |
| GET    | `/v1/playbooks/:playbookId`      | Get a playbook                              | `assets:read`             |
| POST   | `/v1/playbooks`                  | Create a playbook                           | `assets:write`            |
| PATCH  | `/v1/playbooks/:playbookId`      | Edit a playbook                             | `assets:write`            |
| DELETE | `/v1/playbooks/:playbookId`      | Delete a playbook                           | `assets:delete`           |
| POST   | `/v1/playbooks/:playbookId/copy` | Copy a shared playbook as your own playbook | `assets:write`            |

### GET`/v1/playbooks`

Lists playbooks, ordered by usage count (then by creation time, newest first). Cursor-based pagination is supported.

#### Query Parameters

| Parameter     | Type      | Default | Description                                                                                         |
| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------- |
| `active_only` | `boolean` | `true`  | Set to false to also include deactivated playbooks. A value other than "true" / "false" returns 400 |
| `limit`       | `integer` | `50`    | Number of items per page (1-100)                                                                    |
| `cursor`      | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response)                              |

#### Request Example

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

#### Response Fields (200 OK)

| Field                              | Type             | Description                                                                                                                                                      |
| ---------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `playbooks`                        | `array`          | Array of playbook objects                                                                                                                                        |
| `playbooks[].playbookId`           | `string`         | Playbook ID (specify this in the Chat playbookId parameter)                                                                                                      |
| `playbooks[].ownerUserId`          | `string`         | User ID of the owner                                                                                                                                             |
| `playbooks[].name`                 | `string`         | Playbook name                                                                                                                                                    |
| `playbooks[].description`          | `string?`        | Description                                                                                                                                                      |
| `playbooks[].category`             | `string?`        | Category                                                                                                                                                         |
| `playbooks[].tags`                 | `array`          | Array of tags (returned with leading and trailing whitespace removed, empty tags removed, and duplicates returned once)                                          |
| `playbooks[].steps`                | `array`          | Array of steps                                                                                                                                                   |
| `playbooks[].steps[].title`        | `string`         | Step title                                                                                                                                                       |
| `playbooks[].steps[].description`  | `string?`        | Step description                                                                                                                                                 |
| `playbooks[].steps[].guidance`     | `array?`         | Array of supplementary instructions                                                                                                                              |
| `playbooks[].steps[].success`      | `string?`        | Completion criteria                                                                                                                                              |
| `playbooks[].sourceConversationId` | `string?`        | ID of the conversation the playbook was created from                                                                                                             |
| `playbooks[].isShared`             | `boolean`        | Whether the playbook is shared                                                                                                                                   |
| `playbooks[].isActive`             | `boolean`        | Whether the playbook is active                                                                                                                                   |
| `playbooks[].shareRequestStatus`   | `string \| null` | Status of the publishing request (see "Publishing Approval for Skills and Playbooks"). shareRequestNote, shareReviewNote, and shareRequestedAt are also included |
| `playbooks[].usageCount`           | `number`         | Number of times used                                                                                                                                             |
| `playbooks[].copyCount`            | `number`         | Number of times copied                                                                                                                                           |
| `playbooks[].createdAt`            | `string`         | Creation time (ISO 8601)                                                                                                                                         |
| `playbooks[].updatedAt`            | `string`         | Last update time (ISO 8601)                                                                                                                                      |
| `hasMore`                          | `boolean`        | Whether a next page exists                                                                                                                                       |
| `cursor`                           | `string`         | Cursor for the next page. Included only when hasMore is true                                                                                                     |

#### Response Example

```json
{
  "playbooks": [
    {
      "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "name": "Weekly report",
      "description": "Generate a weekly report from sales data",
      "category": "Reporting",
      "tags": ["sales", "weekly"],
      "steps": [
        {
          "title": "Fetch data",
          "description": "Fetch sales data for the target period",
          "guidance": ["From Monday to Sunday of the previous week"],
          "success": "At least one record was fetched"
        }
      ],
      "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
}
```

#### Pagination

While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

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

# Second page (use the cursor returned by the first page)
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=50&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"
```

To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

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

#### Error Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `400`  | limit is not an integer between 1 and 100                    |
| `400`  | cursor is invalid (not a value from a previous response)     |
| `400`  | active\_only is not "true" / "false"                         |
| `403`  | Has neither chat:exec nor assets:read                        |
| `403`  | Called with a system integration token (`code: "forbidden"`) |

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

Lists shared playbooks. The list also includes playbooks you shared and playbooks deactivated by the users who shared them. Ordered by the number of copies (then by creation time, newest first). Cursor-based pagination is supported.

#### Query Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

Same form as the list of your playbooks, except that each item does not include `isShared`, `isActive`, or the request status fields.

#### Response Example

```json
{
  "playbooks": [
    {
      "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Weekly report creation",
      "description": "Generate a weekly report from sales data",
      "category": "Reports",
      "tags": [
        "sales",
        "weekly"
      ],
      "steps": [
        {
          "title": "Data retrieval",
          "description": "Retrieve sales data for the target period",
          "guidance": [
            "From Monday to Sunday of last week"
          ],
          "success": "At least one record of data has been retrieved"
        }
      ],
      "usageCount": 12,
      "copyCount": 0,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `400`  | limit is not an integer between 1 and 100                    |
| `400`  | cursor is invalid (not a value from a previous response)     |
| `403`  | Has neither chat:exec nor assets:read                        |
| `403`  | Called with a system integration token (`code: "forbidden"`) |

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

Gets a playbook. You can get your own playbooks and shared playbooks.

#### Path Parameters

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

#### Request Example

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

#### Response Fields (200 OK)

The same fields as an item in the playbook list, plus `digest`. For a playbook shared by another user, `isShared`, `isActive`, and the request status fields are not included, as in the shared list.

| Field    | Type     | Description                                                                                                                                                                                                                          |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `digest` | `string` | The value to send as baseDigest when editing the playbook. It is made from the name, description, category, tags, steps, shared setting, and active setting, and does not change with the usage count, the copy count, or timestamps |

`updatedAt` is updated not only when the content is changed but also each time the playbook is used.

#### Response Example

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Weekly report creation",
  "description": "Generate a weekly report from sales data",
  "category": "Reports",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "Data retrieval",
      "description": "Retrieve sales data for the target period",
      "guidance": [
        "From Monday to Sunday of last week"
      ],
      "success": "At least one record of data has been retrieved"
    }
  ],
  "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"
}
```

#### Error Responses

| Status | code                 | Description                                                           |
| ------ | -------------------- | --------------------------------------------------------------------- |
| `400`  | `invalid_parameter`  | playbookId is not a UUID                                              |
| `403`  | `insufficient_scope` | The assets:read scope is missing                                      |
| `403`  | `forbidden`          | Called with a system integration token                                |
| `404`  | `playbook_not_found` | The playbook does not exist, or it is another user's private playbook |

### POST`/v1/playbooks`

Creates a playbook.

#### Request Body

| Field                 | Type             | Required | Description                                                                                                                                                                                          |
| --------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | `string`         | Yes      | Name (up to 100 characters; cannot be only whitespace)                                                                                                                                               |
| `description`         | `string \| null` | —        | Description (up to 500 characters)                                                                                                                                                                   |
| `category`            | `string \| null` | —        | Category (up to 50 characters)                                                                                                                                                                       |
| `tags`                | `array`          | —        | Tags (up to 10 strings of up to 30 characters each. Empty or whitespace-only tags, and tags that are the same after removing leading and trailing whitespace, cannot be sent. Case is distinguished) |
| `steps`               | `array`          | Yes      | Steps (1 to 20)                                                                                                                                                                                      |
| `steps[].title`       | `string`         | Yes      | Step title (up to 100 characters; cannot be only whitespace)                                                                                                                                         |
| `steps[].description` | `string`         | —        | Step description (up to 1000 characters)                                                                                                                                                             |
| `steps[].guidance`    | `array`          | —        | Supplementary instructions (up to 10 strings of up to 500 characters each; empty or whitespace-only strings cannot be sent)                                                                          |
| `steps[].success`     | `string`         | —        | Completion criteria (up to 500 characters)                                                                                                                                                           |
| `isShared`            | `boolean`        | —        | Whether to share it. Private if omitted                                                                                                                                                              |
| `isActive`            | `boolean`        | —        | Whether it is active. Active if omitted                                                                                                                                                              |
| `shareRequestNote`    | `string \| null` | —        | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks")                                            |

- A step has four fields: `title`, `description`, `guidance`, and `success` (other fields are not saved). `null` cannot be sent for the string fields of a step.
- The name, description, and category are saved with leading and trailing whitespace removed. A description or category that is `null`, an empty string, or only whitespace is saved as `null`.

#### Request Example

**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": "Weekly report creation",
  "description": "Generate a weekly report from sales data",
  "category": "Reports",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "Data retrieval",
      "description": "Retrieve sales data for the target period",
      "guidance": [
        "From Monday to Sunday of last week"
      ],
      "success": "At least one record of data has been retrieved"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': 'Weekly report creation', 'description': 'Generate a weekly report from sales data', 'category': 'Reports', 'tags': ['sales', 'weekly'], 'steps': [{'title': 'Data retrieval', 'description': 'Retrieve sales data for the target period', 'guidance': ['From Monday to Sunday of last week'], 'success': 'At least one record of data has been retrieved'}]},
)

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": "Weekly report creation", "description": "Generate a weekly report from sales data", "category": "Reports", "tags": ["sales", "weekly"], "steps": [{"title": "Data retrieval", "description": "Retrieve sales data for the target period", "guidance": ["From Monday to Sunday of last week"], "success": "At least one record of data has been retrieved"}]}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "Weekly report creation", "description": "Generate a weekly report from sales data", "category": "Reports", "tags": ["sales", "weekly"], "steps": [{"title": "Data retrieval", "description": "Retrieve sales data for the target period", "guidance": ["From Monday to Sunday of last week"], "success": "At least one record of data has been retrieved"}]}`)
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)
```

#### Response (201 Created)

Returns the created playbook in the same form as the response for getting your own playbook.

#### Response Example

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": null,
  "name": "Weekly report creation",
  "description": "Generate a weekly report from sales data",
  "category": "Reports",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "Data retrieval",
      "description": "Retrieve sales data for the target period",
      "guidance": [
        "From Monday to Sunday of last week"
      ],
      "success": "At least one record of data has been retrieved"
    }
  ],
  "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"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                        |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`      | name or steps is missing, or a field has the wrong type, length, or number of items (error.param names the field; a field in a step is shown like steps\[2].title) |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                    |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                                  |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                             |
| `413`  | `body_too_large`         | The body exceeds 3 MiB                                                                                                                                             |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                               |

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

Edits one of your playbooks. Only the fields you send are changed. When you send the steps (`steps`), all steps are replaced (express rewriting, removing, and reordering with this array).

When you change any of the name, description, category, tags, or steps, the previous content is kept as a version, and you can restore it from “Version history” in the web app. Changing only the sharing or enabled setting does not keep a version.

#### Path Parameters

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

#### Request Body

| Field              | Type             | Required | Description                                                                                                                                                                  |
| ------------------ | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseDigest`       | `string`         | Yes      | The digest from the Get Playbook response                                                                                                                                    |
| `name`             | `string`         | —        | Name (up to 100 characters; cannot be only whitespace or null)                                                                                                               |
| `description`      | `string \| null` | —        | Description (up to 500 characters). Send null or an empty string to clear it                                                                                                 |
| `category`         | `string \| null` | —        | Category (up to 50 characters). Send null or an empty string to clear it                                                                                                     |
| `tags`             | `array`          | —        | Tags (up to 10 strings of up to 30 characters each; the tags that cannot be sent are the same as when creating). Send \[] to clear them                                      |
| `steps`            | `array`          | —        | All the steps (1 to 20). The fields are the same as when creating a playbook                                                                                                 |
| `isShared`         | `boolean`        | —        | Whether to share it. In a tenant where publishing approval is enabled, true makes it wait for approval, and sending false to an item awaiting approval withdraws the request |
| `isActive`         | `boolean`        | —        | Whether it is active                                                                                                                                                         |
| `shareRequestNote` | `string \| null` | —        | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks")                    |

Send at least one field besides baseDigest (shareRequestNote does not count). `null` cannot be sent for `name`, `tags`, `steps`, `isShared`, or `isActive`. Values are saved in the same way as when creating a playbook (leading and trailing whitespace), and the tags and supplementary instructions that cannot be sent are also the same.

If the first request changed the content, resending it returns `409 Conflict` (`stale_base`) because the `digest` has changed. Get the playbook again and check whether it was changed.

In a tenant where publishing approval is enabled, changing the content (name, description, category, tags, or steps) of a playbook awaiting approval keeps it awaiting approval, with the changed content. If you change the content of a playbook awaiting approval after the administrator stops requiring approval, the change shares it. This is the same as changing it on the screen (see [Publishing Approval](#assets-share-approval)).

In a tenant where publishing approval is enabled, changing the content of a shared playbook keeps it shared and makes a request (`isShared` in the response is `true`, and `shareRequestStatus` is `"pending"`). Until it is approved, other users see the approved content (see [Publishing Approval](#assets-share-approval)).

#### Request Example

**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": "Create a weekly report from sales data"
}'
```

**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': 'Create a weekly report from sales data'},
)

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": "Create a weekly report from sales data"}),
}
);

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

**Go**

```go
payload := []byte(`{"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E", "description": "Create a weekly report from sales data"}`)
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)
```

#### Response (200 OK)

Returns the edited playbook (with its current `digest`) in the same form as the response for getting your own playbook.

#### Response Example

```json
{
  "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Weekly report creation",
  "description": "Create a weekly report from sales data",
  "category": "Reports",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "Data retrieval",
      "description": "Retrieve sales data for the target period",
      "guidance": [
        "From Monday to Sunday of last week"
      ],
      "success": "At least one record of data has been retrieved"
    }
  ],
  "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"
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                                |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | playbookId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, a field has the wrong type, length, or number of items, or null was sent for a field that does not accept it |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                                                                                            |
| `403`  | `insufficient_scope`     | The assets:write scope is missing                                                                                                                                                                          |
| `403`  | `forbidden`              | Called with a system integration token                                                                                                                                                                     |
| `404`  | `playbook_not_found`     | The playbook does not exist, or it is another user's playbook                                                                                                                                              |
| `409`  | `stale_base`             | The playbook has changed since you got it                                                                                                                                                                  |
| `413`  | `body_too_large`         | The body exceeds 3 MiB                                                                                                                                                                                     |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                       |

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

Deletes one of your playbooks. A system administrator can also delete playbooks shared by other users.

#### Path Parameters

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

#### Query Parameters

| Parameter | Type     | Default   | Description                                                                                                              |
| --------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `force`   | `string` | `"false"` | Set to "true" to delete the playbook even if schedules or Agents use it. A value other than "true" / "false" returns 400 |

- **When the playbook is in use**: If active schedules use this playbook or Agents have it in their definitions, `409 Conflict` (`has_active_references`; the numbers of active schedules and Agents are in `error.message`) is returned. Agents are counted regardless of their owners. Project jobs (sweeps of Agents placed in projects, and project executions that have not started yet) are not counted as schedules.

- **With `force=true`**: The playbook is removed from the definitions of all users' Agents and deleted. The sweeps of those Agents keep running with the definitions after the removal. If active schedules use the playbook, the schedules that use it, including inactive ones, are deleted.

  <!-- -->

  - Only your own schedules are counted and deleted (also when a system administrator deletes their own playbook). Other users' schedules are neither counted nor deleted (they keep pointing to the deleted playbook). When a system administrator deletes a playbook shared by another user, the schedules of all users are counted and deleted.
  - If only inactive schedules use the playbook, `409 Conflict` is not returned unless Agents also use it. In either case, inactive schedules are not deleted even with `force=true`, and they keep pointing to the deleted playbook.
  - Deleted schedules do not run after that (executions that have already started are not stopped).

#### Request Example

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

#### Response (200 OK)

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

#### Error Responses

| Status | code                    | Description                                                                                                    |
| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`     | playbookId is not a UUID, or force is not "true" / "false"                                                     |
| `403`  | `insufficient_scope`    | The assets:delete scope is missing                                                                             |
| `403`  | `forbidden`             | Called with a system integration token                                                                         |
| `404`  | `playbook_not_found`    | The playbook does not exist, or it is another user's playbook that you cannot delete                           |
| `409`  | `has_active_references` | Active schedules or Agents use the playbook (it can be deleted with force=true)                                |
| `409`  | `admin_stopped`         | When deleting with force=true, active schedules use this playbook and an administrator has stopped one of them |

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

Copies a shared playbook as your own playbook. The name, description, category, tags, and steps are copied, and the copy is created as private and active. The number of copies of the source (`copyCount`) increases by 1. No body is required (a body is not read even if sent).

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                                |
| ------------ | -------- | -- | --------------------------------- |
| `playbookId` | `string` | 必須 | ID of the playbook to copy (UUID) |

#### Request Headers

| Header            | Required | Description                                                                                                                                                                                     |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | —        | A key to identify resends (8 to 128 characters of letters, digits, and \_ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |

#### Request Example

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

#### Response (201 Created)

Returns the playbook created by the copy in the same form as the response for getting your own playbook.

If you resend with the same `Idempotency-Key`, `200 OK` is returned with the first copy (its current contents) in the same form. If the first copy has been deleted, `404 Not Found` (`playbook_not_found`) is returned; send the request with a new key.

#### Response Example

```json
{
  "playbookId": "1d3f5a7b-9c2e-4a6c-8e0f-2b4d6f8a0c1e",
  "ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "sourceConversationId": null,
  "name": "Weekly report creation",
  "description": "Generate a weekly report from sales data",
  "category": "Reports",
  "tags": [
    "sales",
    "weekly"
  ],
  "steps": [
    {
      "title": "Data retrieval",
      "description": "Retrieve sales data for the target period",
      "guidance": [
        "From Monday to Sunday of last week"
      ],
      "success": "At least one record of data has been retrieved"
    }
  ],
  "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"
}
```

#### Error Responses

| Status | code                      | Description                                                                                                                                                                                               |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`       | playbookId is not a UUID                                                                                                                                                                                  |
| `400`  | `idempotency_key_invalid` | The format of Idempotency-Key is invalid                                                                                                                                                                  |
| `403`  | `insufficient_scope`      | The assets:write scope is missing                                                                                                                                                                         |
| `403`  | `forbidden`               | Called with a system integration token                                                                                                                                                                    |
| `404`  | `playbook_not_found`      | The playbook does not exist, is not shared (even your own playbook returns 404 if it is not shared), or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
| `409`  | `idempotency_conflict`    | A copy of a different playbook was sent with the same Idempotency-Key                                                                                                                                     |

## Search

Full-text search messages.

### Endpoint List

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

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

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

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

#### Query Parameters

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

#### Request Example

**Search messages**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=sales" \
-H "Authorization: Bearer <access_token>"
```

**Python**

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

query = "sales"
response = requests.get(
  "https://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 = "sales";
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 := "sales"
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)
```

#### Response Fields (200 OK)

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

#### Response Example

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

#### Error Response

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

## User

Retrieve, update user information, and change password.

### Endpoint List

| メソッド  | エンドポイント             | 説明                      |
| ----- | ------------------- | ----------------------- |
| GET   | `/v1/user`          | Get user information    |
| PATCH | `/v1/user`          | Update user information |
| POST  | `/v1/user/password` | Change password         |

### GET`/v1/user`

Get user information.

#### Request Example

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

#### Response Fields (200 OK)

| Field                | Type      | Description                                                     |
| -------------------- | --------- | --------------------------------------------------------------- |
| `userId`             | `string`  | Unique identifier of the user                                   |
| `email`              | `string`  | Email address                                                   |
| `username`           | `string`  | Username                                                        |
| `emailVerified`      | `boolean` | Email verification status                                       |
| `createdAt`          | `string`  | Account creation date and time (ISO 8601)                       |
| `isApproved`         | `boolean` | Account approval status                                         |
| `role`               | `string`  | User role                                                       |
| `organization`       | `object`  | Organization (included only when set)                           |
| `organization.value` | `string`  | Organization code                                               |
| `organization.label` | `string`  | Organization name                                               |
| `jobType`            | `object`  | Job type (included only when set)                               |
| `jobType.value`      | `string`  | Job type code                                                   |
| `jobType.label`      | `string`  | Job type name                                                   |
| `bio`                | `string`  | Bio (included only when set)                                    |
| `lastLoginAt`        | `string`  | Last login date and time (ISO 8601, included only when present) |

#### Response Example

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "John Doe",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "Engineering Department" },
  "jobType": { "value": "dev", "label": "Developer" },
  "bio": "AI Engineer",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

#### Error Response

| Status | code             | Description                                                       |
| ------ | ---------------- | ----------------------------------------------------------------- |
| `500`  | `internal_error` | The user information could not be retrieved (retry after a while) |

### PATCH`/v1/user`

Update user information.

#### Request Body

| パラメータ          | 型        | 必須 | 説明                                                                                                                                                                                                                                                                                                                  |
| -------------- | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`     | `string` | —  | Username. 2 to 50 characters; <, >, ", and ' cannot be used                                                                                                                                                                                                                                                         |
| `organization` | `string` | —  | Organization code. Up to 100 characters. It can be set only while it is not set, and only to a valid organization code. Changing an organization that is already set (including clearing it) returns 403. Ask an administrator to change it. If it is synced from the identity provider (IdP), change it in the IdP |
| `jobType`      | `string` | —  | Job type code. Up to 100 characters. It can be set only while it is not set, and only to a valid job type code. Changing a job type that is already set (including clearing it) returns 403. Ask an administrator to change it. If it is synced from the identity provider (IdP), change it in the IdP              |
| `bio`          | `string` | —  | Bio. Up to 150 characters; <, >, ", and ' cannot be used                                                                                                                                                                                                                                                            |

#### Request Example

**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": "John Doe", "bio": "Engineering Department" }'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
  headers={"Authorization": f"Bearer {token}"},
  json={"username": "John Doe", "bio": "Engineering Department"},
)

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: "John Doe",
    bio: "Engineering Department",
  }),
}
);

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

**Go**

```go
payload := map[string]string{
  "username": "John Doe",
  "bio": "Engineering Department",
}
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)
```

#### Response Fields (200 OK)

Returns the same user object as GET /v1/user (with updated values).

#### Response Example

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "John Doe",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "Engineering Department" },
  "jobType": { "value": "dev", "label": "Developer" },
  "bio": "Engineering Department",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

#### Error Response

| Status | code                     | Description                                                                                                                                                                                                           |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | No field to update was specified                                                                                                                                                                                      |
| `400`  | `invalid_body`           | The body is malformed JSON                                                                                                                                                                                            |
| `400`  | `invalid_parameter`      | Invalid input (username / organization / jobType / bio is not a string, has an invalid length or characters, or an organization / jobType being set for the first time is not a valid code)                           |
| `403`  | `affiliation_locked`     | An attempt was made to change an organization / jobType that is already set (including clearing it). Ask your administrator to change it. If it is synchronized from an IdP, change it in the identity provider (IdP) |
| `409`  | `conflict`               | Another update of the same user is being processed. Wait a moment and retry                                                                                                                                           |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                                                                                                  |

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

Change password.

#### Request Body

| パラメータ             | 型        | 必須 | 説明                          |
| ----------------- | -------- | -- | --------------------------- |
| `currentPassword` | `string` | 必須 | Current password            |
| `newPassword`     | `string` | 必須 | New password                |
| `confirmPassword` | `string` | 必須 | New password (confirmation) |

#### Request Example

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

#### Response Fields (200 OK)

| Field     | Type      | Description                               |
| --------- | --------- | ----------------------------------------- |
| `userId`  | `string`  | Unique identifier of the user             |
| `changed` | `boolean` | Always true on successful password change |

#### Response Example

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

After you change the password, do not keep using the tokens obtained before the change; sign in again and get new tokens. An access token obtained before the change can still be used with the API until it expires.

Changing the password also signs the user out of the chat on every device, the next time they use it.

#### Error Response

| Status | Description                                                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing required parameters, currentPassword / newPassword / confirmPassword is not a string, the body is malformed JSON (`code: "invalid_body"`), password validation failed, or the current password is incorrect |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                    |
| `401`  | Authentication token is invalid                                                                                                                                                                                     |
| `403`  | The user signs in with SSO (`code: "federation_only_user"`). SSO users cannot change their password with this API                                                                                                   |

## Master Data

Retrieve master data such as organizations and job types.

### Endpoint List

| メソッド | エンドポイント             | 説明                 |
| ---- | ------------------- | ------------------ |
| GET  | `/v1/organizations` | List organizations |
| GET  | `/v1/job-types`     | List job types     |
| GET  | `/v1/personas`      | List personas      |

### GET`/v1/organizations`

List organizations. Inactive organizations are not included.

#### Request Example

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

#### Response Fields (200 OK)

| Field                   | Type      | Description                             |
| ----------------------- | --------- | --------------------------------------- |
| `organizations`         | `array`   | Array of organization objects           |
| `organizations[].value` | `string`  | Organization code                       |
| `organizations[].label` | `string`  | Organization name                       |
| `hasMore`               | `boolean` | Always false (pagination not supported) |

#### Response Example

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

#### Error Response

| Status | code             | Description                                                            |
| ------ | ---------------- | ---------------------------------------------------------------------- |
| `500`  | `internal_error` | The list of organizations could not be retrieved (retry after a while) |

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

List job types. Inactive job types are not included.

#### Request Example

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

#### Response Fields (200 OK)

| Field              | Type      | Description                             |
| ------------------ | --------- | --------------------------------------- |
| `jobTypes`         | `array`   | Array of job type objects               |
| `jobTypes[].value` | `string`  | Job type code                           |
| `jobTypes[].label` | `string`  | Job type name                           |
| `hasMore`          | `boolean` | Always false (pagination not supported) |

#### Response Example

```json
{
  "jobTypes": [
    { "value": "dev", "label": "Developer" },
    { "value": "pm", "label": "Project Manager" }
  ],
  "hasMore": false
}
```

#### Error Response

| Status | code             | Description                                                        |
| ------ | ---------------- | ------------------------------------------------------------------ |
| `500`  | `internal_error` | The list of job types could not be retrieved (retry after a while) |

### GET`/v1/personas`

Retrieves the list of personas (agent response personalities). Use a returned `personaKey` to specify a persona in Chat / MCP / A2A.

#### Query Parameters

| パラメータ    | 型        | 必須 | デフォルト                       | 説明                                                                                                                                                                  |
| -------- | -------- | -- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale` | `string` | —  | `Platform default language` | Display language for name / description (for example "ja", "en"). An unknown value or a non-string value does not return 400; the platform default language is used |

#### Request example

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

#### Response Fields (200 OK)

| Field                    | Type      | Description                                                                                                                                                                     |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale`                 | `string`  | The resolved locale. A persona with no content in the requested language is returned with its content in another language, in the order English, Japanese, then other languages |
| `personas`               | `array`   | Array of persona objects                                                                                                                                                        |
| `personas[].personaKey`  | `string`  | Persona identifier (specify as personaKey in Chat / MCP / A2A)                                                                                                                  |
| `personas[].name`        | `string`  | Persona display name                                                                                                                                                            |
| `personas[].description` | `string`  | Persona description                                                                                                                                                             |
| `hasMore`                | `boolean` | Always false (pagination not supported)                                                                                                                                         |

#### Response Example

```json
{
  "locale": "en",
  "personas": [
    { "personaKey": "concise", "name": "Concise", "description": "Answers concisely, focusing on key points" }
  ],
  "hasMore": false
}
```

#### Error Response

| Status | code             | Description                                                       |
| ------ | ---------------- | ----------------------------------------------------------------- |
| `500`  | `internal_error` | The list of personas could not be retrieved (retry after a while) |

## Projects

The project APIs are in the [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md). For calls made with a system integration token (Client Credentials flow), see [System Integration API Reference — Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md#projects).

### List Projects

`GET /v1/projects` is in [Projects in the User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#projects).

### Start a Workflow Run

`POST /v1/projects/{projectId}/runs` is in [Workflow Runs in the User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#runs).

### Fire a Trigger

`POST /v1/projects/{projectId}/triggers/{triggerId}/fire` is in [Triggers in the User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#triggers).

### Get a Workflow Run

`GET /v1/projects/{projectId}/runs/{runId}` is in [Workflow Runs in the User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#runs).

## Error Responses

### HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

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

### Error Response Format

All error responses are returned in the following common structure.

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

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

### Suspended users

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

The following APIs do not check whether the user is suspended: `GET /v1/organizations`, `GET /v1/job-types`, `GET /v1/personas`, `GET /v1/user`, `PATCH /v1/user`, and the MCP tools `list_personas` and `cancel_chat` (when no task is in progress). They can still be called after the suspension until the access token expires. A suspended user cannot refresh the access token.

### When the Request Is Stopped Before Reaching the API

If a layer in front of the API (such as a security inspection) returns an HTML error page, the response is replaced with JSON in the common format above. In that case, `error.code` is one of the following.

| Status                     | error.code           | Description                                                                                                                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403                        | `waf_blocked`        | The request was stopped by a security inspection in front of the API. If the request is legitimate, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |
| 4xx and 5xx other than 403 | `upstream_api_error` | The request was rejected by, or caused an error in, a layer in front of the API. If this continues, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |

| Field             | Type     | Description                                                                                                                            |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `error.reference` | `string` | Reference number for a request stopped before reaching the API. Include it when contacting support. Omitted when no value is available |

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