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. For the Marketplace edition, see the System Integration API Reference (Marketplace).

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.

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 and the Authentication API Reference.

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, Messages, Files, Library, Agents, Skills, Playbooks and 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.

Request handling

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

• Query parameters and body fields that are not in the specification are ignored. However, a field that the service accepts but this page does not document may still return 400 Bad Request if its type or value is invalid.
• An invalid value for a documented query parameter returns 400 Bad Request.
• A malformed JSON body returns 400 Bad Request (invalid_body).
• Sending a body with a Content-Type other than application/json to an endpoint that accepts a JSON body returns 415 Unsupported Media Type (unsupported_media_type). File uploads return 415 for a body other than multipart/form-data. However, if reading the body fails first with 400 (malformed JSON) or 413 (over the size limit), that error is returned instead.
• A body field of the wrong type returns 400 Bad Request.
• Responses include an x-request-id header. The service assigns this value, and a value sent in the request is not used. When you contact support, please tell us this value.

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

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	Persona (response personality) to apply. Specify a personaKey returned by `GET /v1/personas`. Omit to apply no persona.
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). "markdown" preserves Markdown as-is.

Message Object

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

Content Parts (Array Format)

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

type	Parameter	Description
"text"	text (string)	Text message
"input_file"	fileId 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

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5  "model": "AGENTIC STAR",
6  "stream": true,
7  "messages": [
8    {
9      "role": "user",
10      "content": "Please analyze the sales data"
11    }
12  ]
13}'

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.

Response Example

SSE

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")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	Missing chat:exec scope
404	The specified input_file fileId or filepath is not found
409	The specified conversation is currently being processed

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

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

Response (200 OK)

Reconnects to the SSE stream. The response format is the same as POST /v1/chat/completions. The response headers include X-Conversation-Id and X-Message-Id. For detailed reconnection procedures, see the Streaming Guide.

Error Response

Status	Description
400	Invalid conversationId
403	Missing chat:exec scope
404	Conversation not found or not in progress

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

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json"

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")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	Missing chat:exec scope
404	Conversation not found

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

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

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

Parameter	Type	Default	Description
limit	integer	50	Number of items to retrieve (1-100)
cursor	string	—	Cursor for fetching the next page (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 queries a different data store, so cursor cannot be carried over

Request Example

List conversations

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc" \
2-H "Authorization: Bearer <access_token>"

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[].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",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}

Error Response

Status	Description
400	Invalid limit parameter (outside the range of 1-100), mode is not "active" / "archive", order is not "asc" / "desc", or title is not a string (for example, specified more than once)
403	Missing chat:history scope

GET/v1/conversations/:conversationId/messages

Retrieve the message history of a specified conversation. Cursor-based pagination is supported.

Path Parameters

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

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)
order	string	"desc"	"asc" or "desc"

Request Example

Get messages

1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
2-H "Authorization: Bearer <access_token>"

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	Message body text
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)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted when it cannot be determined
messages[].deliverables[].size	number?	File size (bytes). Omitted when 0 or below
messages[].files	array?	Array of user-uploaded files. Included only when present for messages with sender: "User"
messages[].files[].fileId	string	Unique identifier of the file (UUID)
messages[].files[].mimeType	string	MIME type (e.g., "image/png", "application/pdf")
messages[].files[].width	number?	Image width in pixels. Only for image files
messages[].files[].height	number?	Image height in pixels. Only for image files
messages[].archived	boolean?	true only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with GET /v1/conversations?mode=archive
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Task Object

Field	Type	Description
messageId	string	ID of the message the task belongs to
conversationId	string	ID of the conversation the task belongs to
callId	string?	Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call
actionType	string	Type of task (e.g., tool execution, code generation)
title	string?	Task title. Omitted when not present
description	string?	Task description. Omitted when not present
status	string	Task status. One of: "in_progress" / "completed" / "failed" / "error" / "pending"
content	string?	Task execution result text. Omitted when not present
metadata	object?	Auxiliary information that varies by actionType (sub_event_type, url, filepath, etc.). See the Streaming Guide 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.

The object has the same structure as in SSE. For field details, see Streaming Guide — 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.

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.

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

1# First page
2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50" \
3-H "Authorization: Bearer <access_token>"
4
5# Second page (use the cursor returned by the first page)
6curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
7-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	Description
400	Invalid conversationId format
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
400	order is not "asc" / "desc"
403	Missing chat:history scope
404	Conversation not found

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

Retrieves the HTML of a UI resource. Pass the tool_call_id found in SSE delta.uiResource, in tasks[].metadata.uiResource 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

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

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

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 not a valid UUID	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.

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

1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "title": "New title" }'

Response Fields (200 OK)

Field	Type	Description
conversationId	string	Conversation ID (UUID)
title	string	Updated title
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)

Response Example

JSON

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

Error Response

Status	Description
400	title is missing, empty, or exceeds 200 characters, the body is malformed JSON (code: "invalid_body"), or the conversation is archived (code: "conversation_archived")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	Missing chat:history scope
404	Conversation not found

DELETE/v1/conversations/:conversationId

Delete a conversation.

Path Parameters

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

Request Example

Delete conversation

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

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	Description
400	Invalid conversationId, or the conversation is archived (code: "conversation_archived"; use POST /v1/conversations/:id/restore to restore it)
403	Missing chat:history scope
404	Conversation not found
409	Conversation cannot be deleted because it is currently being processed

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

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

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	Description
400	Invalid conversationId
403	Missing chat:history scope
404	No matching conversation in archive, or it is already active (archive state is not distinguished)

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/:file_id/content	Download a file	chat:file
DELETE	/v1/files/:file_id	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

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/files \
2-H "Authorization: Bearer <access_token>" \
3-F "file=@report.pdf" \
4-F "filename=report.pdf"

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	Description
400	file or filename parameter is missing, file size exceeds 512 MB, or the uploaded image file is corrupted or invalid
415	The body is not multipart/form-data (code: "unsupported_media_type")
403	Missing chat:file scope

GET/v1/files

List files. 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)
order	string	"desc"	"asc" or "desc"

Request Example

List files

1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?order=desc \
2-H "Authorization: Bearer <access_token>"

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

1# First page
2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \
3-H "Authorization: Bearer <access_token>"
4
5# Second page (use the cursor returned by the first page)
6curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
7-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	Description
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
400	order is not "asc" / "desc"
403	Missing chat:file scope

GET/v1/files/:file_id/content

Download a file.

Path Parameters

パラメータ	型	必須	説明
file_id	string	必須	File ID (UUID)

Request Example

Download file

1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \
2-H "Authorization: Bearer <access_token>" \
3-o downloaded_file.pdf

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"

Error Response

Status	Description
400	Invalid fileId format
403	Missing chat:file scope
404	File not found

DELETE/v1/files/:file_id

Delete a file.

Path Parameters

パラメータ	型	必須	説明
file_id	string	必須	File ID (UUID)

Request Example

Delete file

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

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	Description
400	Invalid fileId format
403	Missing chat:file scope
404	File 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.

Query Parameters

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

Request Example

Get artifact file

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy?path=/path/to/artifact.xlsx" \
2-H "Authorization: Bearer <access_token>" \
3-o artifact.xlsx

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	Description
400	path parameter is missing or has an invalid format
403	None of chat:exec / a2a:all / mcp:all is present
404	File not found

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

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"

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": "/path/to/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

Common Rules for Agents, Playbooks, and Skills

These rules apply to the APIs that read, create, edit, delete, and copy Agents, Playbooks, and Skills.

• Scopes: Reading requires assets:read; creating, editing, and copying require assets:write; deleting requires assets:delete. The skill and playbook lists can also be called with chat:exec.
• System integration tokens cannot be used. Calling with one returns 403 Forbidden (forbidden).
• What you can read: Your own resources and shared ones. Another user's private resource, or one that does not exist, returns 404 Not Found (agent_not_found, playbook_not_found, or skill_not_found).
• Editing and deleting: Only your own resources (a system administrator can also delete playbooks and skills shared by other users). Another user's resource returns 404 Not Found. To change another user's resource, copy it to your own and change the copy. When deleting, 409 Conflict may be returned first even for playbooks and skills shared by other users if Agents use them. The same applies to playbooks used by schedules (see each API).
• Editing: Send the digest from the get API as baseDigest. If another change was made after you got it, 409 Conflict (stale_base) is returned. Get it again and resend.
• Creating and copying: Resending creates another one (except when copying a registered Agent of the Marketplace edition; see Copy Agent). If you did not receive a response, check whether it was created using the IDs and createdAt in the list before resending.
• Body size limit: A JSON body can be up to 3 MiB. A larger body returns 413 Payload Too Large (body_too_large). For the skill APIs that send files, see the limit in each API.
• The Agent APIs return 403 Forbidden (sso_required) for a token of a user who does not sign in with SSO.

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)

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

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). The query parameters, response, and errors are the same as for listing your own Agents.

GET/v1/agents/:agentId

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

Path Parameters

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

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
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 also counted)
copyCount	number | null	Number of times it has been copied
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, 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,
  "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": "6f1c2a9e0b7d…"
}

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. 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, only the files of the user who created the project are passed
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.

Response (201 Created)

Returns the created Agent in the same form as the Get Agent response.

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 (for a skill with 100 or more versions, invalid_spec is returned)
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
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, and spec.

When you change spec, the playbook, skills, and input files the definition points to are checked, including fields you did not send. An Agent copied from a shared Agent still points to the original user's playbook, skills, and input files, so unless you change them to your own (skills may also be shared ones), 400 is returned.

Response (200 OK)

Returns the edited Agent (with a new digest) in the same form as the Get Agent response.

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 in the definition is neither your own skill nor an active shared skill
400	version_not_found	A skill versionId in the definition is not a version of that skill (for a skill with 100 or more versions, invalid_spec is returned)
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_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

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, including placements in deleted projects (it can be deleted with force=true; read the number of projects from projectCount in the Get Agent response)
409	agent_running	A sweep of this Agent is running

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 remain the original user's. To change them to your own, edit the copied Agent. 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)

Response (201 Created)

Returns the Agent created by the copy in the same form as the Get Agent response. 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).

Error Responses

Status	code	Description
400	invalid_parameter	agentId is not a UUID
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 private Agent
409	already_owned	You tried to copy your own 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.

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)

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[].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,
      "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.

curl

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

Response Fields (200 OK)

Shared skills are always active, so the isShared / isActive fields are not included.

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)

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 and isActive 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,
  "createdAt": "2026-08-01T03:12:45.123Z",
  "updatedAt": "2026-08-05T09:00:00.000Z",
  "currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
  "digest": "9d2e41c7a0b3…"
}

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 with the single-file API (to read all its files, copy the skill with that version).

Path Parameters

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

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), or "baseline" (content from before versions were recorded)
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": "78a4ea5aade3…",
      "createdAt": "2026-08-05T09:00:00.000Z",
      "isCurrent": true
    },
    {
      "versionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
      "versionNo": 1,
      "parentVersionId": null,
      "source": "upload",
      "contentDigest": "3cd01ce0220c…",
      "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
versionId	string	Current version	ID of the version to read (UUID)

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 of the current version)
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)

Response Example

JSON

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

Error Responses

Status	code	Description
400	invalid_parameter	skillId or versionId is not a UUID
400	version_not_found	versionId 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, only documents (kind is "document" and the file is not binary) can be read. Other files of an earlier version 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)
versionId	string	Current version	ID of the version to read (UUID)

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)

Error Responses

Status	code	Description
400	invalid_parameter	skillId or versionId is not a UUID, or path is missing
400	file_not_found	The file at path is not in the version
400	version_not_found	versionId is not a version of the skill
400	version_not_readable	A file that is not a document, or a binary document, was specified in an earlier 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 of the current version of a skill (including setting files and images) 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

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

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.

Response (201 Created)

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

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)

curl

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).
• 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 (of the current version)
files	file	Yes	Files of the skill. How to send them and the rules are the same as when creating a skill

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

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.

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. Get the digest of the new version from the file list.

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

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 (of the current version)
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": "WyI1YjFkN2UyYS04YzRm…",
  "changes": [
    { "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: Generates release notes\n---\n\n# Steps\n..." },
    { "path": "templates/old.md", "deleted": true }
  ]
}

Response (201 Created)

Field	Type	Description
skill	object	The skill after the edit (same form as the response for getting your own 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.

Error Responses

Status	code	Description
400	invalid_parameter	skillId is not a UUID, baseDigest is missing, empty, or not a string, or changes[].deleted is not true or false
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
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
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

Send at least one field besides baseDigest. 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.

Response (200 OK)

Returns the changed skill (with its current digest) in the same form as the response for getting your own skill.

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
cascade	string	"false"	Set to "true" to remove the skill from the schedules that use it and then delete the skill. A value other than "true" / "false" returns 400
force	string	"false"	Set to "true" to delete the skill even if Agents use it. A value other than "true" / "false" returns 400

• When Agents use the skill: If Agents have this skill in their definitions, 409 Conflict (skill_in_use; the number of Agents is in error.message) is returned. Agents are counted regardless of their owners. You can delete the skill with force=true. After the deletion, the Agents keep pointing to the deleted skill. This check is done before checking whether you may delete the skill, so 409 Conflict may be returned even for a skill shared by another user.
• When schedules use the skill: If schedules use this skill, 409 Conflict (skill_referenced; the number of schedules is in error.message) is returned. The schedules of all users are counted, whether active or inactive. Sweeps of Agents placed in projects and similar jobs are also counted as schedules. With cascade=true, the skill is removed from those schedules and then deleted. The schedules themselves are kept.
• If both Agents and schedules use the skill, both cascade=true and force=true are required.

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 cascade 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_in_use	Agents use the skill (it can be deleted with force=true)
409	skill_referenced	Schedules use the skill (it can be deleted with cascade=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) 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 Body

Field	Type	Required	Description
versionId	string	—	ID of the version to copy (UUID). The current version if omitted

Response (201 Created)

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

Error Responses

Status	code	Description
400	invalid_parameter	skillId or versionId is not a UUID
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, or it is another user's private skill
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.

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)

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[].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,
      "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.

curl

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

Response Fields (200 OK)

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

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)

Response Fields (200 OK)

The same fields as an item in the playbook list, plus digest. For a playbook shared by another user, isShared and isActive 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.

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

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

Response (201 Created)

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

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

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
isActive	boolean	—	Whether it is active

Send at least one field besides baseDigest. 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.

Response (200 OK)

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

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
cascade	string	"false"	Set to "true" to delete the schedules that use this playbook and then delete the playbook. A value other than "true" / "false" returns 400
force	string	"false"	Set to "true" to delete the playbook even if Agents use it. A value other than "true" / "false" returns 400

• When schedules use the playbook: If active schedules use this playbook, 409 Conflict (has_active_references; the number of schedules is in error.message) is returned. Sweeps of Agents placed in projects, and project executions that have not started yet, are also counted as schedules (executions that have started are not counted). With cascade=true, the schedules that use this playbook, including inactive ones, are deleted and then the playbook is deleted.
  • For a regular user, only the user's own schedules are counted and deleted. Other users' schedules are neither counted nor deleted (they keep pointing to the deleted playbook). For a system administrator, the schedules of all users are counted and deleted.
  • If only inactive schedules use the playbook, 409 Conflict is not returned, and those schedules are not deleted even with cascade=true. Schedules that are not deleted keep pointing to the deleted playbook.
  • Schedules deleted with cascade=true do not run after that (executions that have already started are not stopped). A sweep stays stopped even if its setting remains enabled.
• When Agents use the playbook: If Agents have this playbook in their definitions, 409 Conflict (playbook_in_use; the number of Agents is in error.message) is returned. Agents are counted regardless of their owners. You can delete the playbook with force=true. After the deletion, the Agents keep pointing to the deleted playbook.
• If both schedules and Agents use the playbook, both cascade=true and force=true are required.
• Schedules and Agents are checked before checking whether you may delete the playbook. For this reason, 409 Conflict may be returned even for a playbook shared by another user. For a playbook you cannot delete, adding cascade=true and force=true returns 404 Not Found, and nothing is deleted.

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 cascade 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 use the playbook (it can be deleted with cascade=true)
409	playbook_in_use	Agents use the playbook (it can be deleted with force=true)

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)

Response (201 Created)

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

Error Responses

Status	code	Description
400	invalid_parameter	playbookId is not a UUID
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 is not shared (even your own playbook returns 404 if it is not shared)

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.

Query Parameters

パラメータ	型	必須	説明
q	string	必須	Search query
order	string	—	Sort order. "asc" (ascending) or "desc" (descending, default)

Request Example

Search messages

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

Response Fields (200 OK)

Field	Type	Description
messages	array	Array of search result messages (up to 50)
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 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)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted 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 for details
hasMore	boolean	Always false (pagination not supported). It is false even when more than 50 messages match, so there is no guarantee that every match is included

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), or order is not "asc" / "desc"
403	Missing chat:history scope

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

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

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

PATCH/v1/user

Update user information.

Request Body

パラメータ	型	必須	説明
username	string	—	Username
organization	string	—	Organization code
jobType	string	—	Job type code
bio	string	—	Bio

Request Example

Update user

1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{ "username": "John Doe", "bio": "Engineering Department" }'

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	Description
400	No fields specified for update
400	username / organization / jobType / bio is not a string, or the body is malformed JSON (code: "invalid_body")
415	The body Content-Type is not application/json (code: "unsupported_media_type")

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

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

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 }

Error Response

Status	Description
400	Missing required parameters, currentPassword / newPassword / confirmPassword is not a string, the body is malformed JSON (code: "invalid_body"), or password validation failed
415	The body Content-Type is not application/json (code: "unsupported_media_type")
401	Authentication token is invalid or current password is incorrect

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

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

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
}

GET/v1/job-types

List job types. Inactive job types are not included.

Request Example

List job types

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

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
}

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

Parameter	Type	Default	Description
locale	string	Platform default language	Display language for name / description (e.g., "ja", "en"). An unknown or non-string value does not return 400; the platform default language is used instead

Response Fields (200 OK)

Field	Type	Description
locale	string	The resolved locale
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
}

Projects

The project APIs are in the User API Reference (Projects). For calls made with a system integration token (Client Credentials flow), see System Integration API Reference — Projects.

List Projects

GET /v1/projects is in Projects in the User API Reference (Projects).

Start a Workflow Run

POST /v1/projects/{projectId}/runs is in Workflow Runs in the User API Reference (Projects).

Fire a Trigger

POST /v1/projects/{projectId}/triggers/{triggerId}/fire is in Triggers in the User API Reference (Projects).

Get a Workflow Run

GET /v1/projects/{projectId}/runs/{runId} is in Workflow Runs in the User API Reference (Projects).

Error Responses

HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

Status	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Token is invalid or missing
403 Forbidden	No access permission to the resource
404 Not Found	Resource does not exist
409 Conflict	Operation conflict, such as the resource currently being processed
413 Payload Too Large	Request body exceeds the size limit
415 Unsupported Media Type	The request body format (Content-Type) is not supported
429 Too Many Requests	Rate limit or concurrent-run limit exceeded. error.type is rate_limit_error, and error.code depends on the endpoint (for example monthly_quota_exceeded for the monthly limit and too_many_active_runs for concurrent project runs). Please wait and retry.
500 Internal Server Error	Internal server error
502 Bad Gateway	Communication error with upstream services (authentication / chat backends, etc.)
503 Service Unavailable	Service temporarily unavailable
504 Gateway Timeout	Upstream service response timeout

Error Response Format

All error responses are returned in the following common structure.

Field	Type	Description
error.type	string	Error classification. One of: "invalid_request_error", "authentication_error", "insufficient_scope_error", "forbidden_error", "not_found_error", "conflict_error", "payload_too_large_error", "rate_limit_error", "server_error", "upstream_error"
error.message	string	Human-readable error message
error.code	string	Machine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token")
error.param	string	The parameter that caused the error. Included only for validation errors
error.suggested_action	string	Recommended action to take. Included only for some errors

JSON

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