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.
https://api.fd.agenticstar.tm.softbank.jp/apiEndpoint paths in this document are relative to the base URL.
Authentication
Every API request must include a Bearer token in the Authorization header. This page describes calls with a token obtained by an application (Authorization Code flow). A token of a system integration (Client Credentials flow) cannot hold chat scopes, so it cannot be used for chat (it can call part of projects; see System Integration API Reference — Projects).
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.
Common Rules
These rules apply to the APIs on this page.
How requests are handled
The APIs on this page handle requests as follows. See each endpoint's description and error responses for endpoint-specific handling.
| What you sent | How it is handled |
|---|---|
| Query parameters and body fields not in the specification | Ignored. However, even items not listed on this page may return 400 Bad Request if their type or value is wrong, when the service accepts them |
| An invalid value for a query parameter in the specification | 400 Bad Request |
An invalid URL encoding in a path parameter value (a % sequence) | 400 Bad Request (invalid_parameter) |
| A malformed JSON body | 400 Bad Request (invalid_body) |
A body other than Content-Type: application/json, or a body with an unsupported character set (charset), sent to an endpoint that accepts a JSON body | 415 Unsupported Media Type (unsupported_media_type) |
A body other than multipart/form-data sent to a file upload | 415 Unsupported Media Type |
| A body field of the wrong type | 400 Bad Request |
If reading the body results in 400 (malformed JSON and so on) or 413 (the size limit was exceeded and so on), that is returned before 415.
Responses carry an x-request-id header. The service assigns this value; a value you send in the request is not used. Please tell us this value when you contact us.
Pagination
List endpoints support cursor-based pagination.
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of items per page (1-100). Defaults to 50. |
cursor | string | Cursor value for the next page. Pass the cursor from the previous response as is. |
order | string | Sort order: "asc" or "desc" (default). Any other value returns 400 Bad Request. Supported on some endpoints only. |
Responses include a hasMore field. While it is true, pass the cursor value in the next request to retrieve the following page.
Cursor-based pagination is available on the list endpoints of Conversations, Messages, Files, Message search, 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.
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
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
agentLevel | string | "default" or "high_performance". Defaults to "default" when omitted. |
agentMode | boolean | Enable/disable agent mode. Defaults to true when omitted. |
privateMode | boolean | Enable/disable private mode. Defaults to false when omitted. |
reportMode | string | "with" (default) or "without". Controls whether a work report is generated on completion. |
personaKey | string | Specifies the persona (response character) for the agent. Pass a personaKey returned by GET /v1/personas. If omitted, no persona is applied. A value not in the list returns 400. |
playbookId | string | Playbook (predefined procedure) to apply. Specify a playbookId returned by GET /v1/playbooks. Omit to apply no playbook. Returns 400 if the ID does not exist or has been deactivated. |
skillIds | array | Array of skill IDs to load into the agent (up to 10). Specify skillId values returned by GET /v1/skills. Returns 400 if 11 or more are specified. IDs that do not exist or are unavailable are ignored, and execution continues with the remaining skills. |
outputFormat | string | Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept, and links become "text (URL)"). "markdown" preserves Markdown as-is. |
interactionReply | object | A mark that the message answers the agent's question. In the form { interactionId, optionIndex? }, send the interactionId of a question waiting for an answer in this conversation (delta.interaction.interactionId in streaming, or tasks[].metadata.interactionId in the conversation history) and, for an answer chosen from the options, the number of the chosen option (0 to 9, starting from 0). With it, the message is recorded as the answer to that question, and you can answer even after the monthly usage limit is used up. Send it with conversationId. 400 (invalid_parameter) if it is malformed, has an unknown field, is not the ID of a question waiting for an answer in this conversation, or the number is outside the options. |
Message Object
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
role | string | 必須 | Use "user". "assistant" / "system" are accepted but only "user" is effectively used as the starting point of the agent turn in the current implementation |
content | string | array | 必須 | The message content. A string, or an array of content parts (text / input_file). The text to be processed must be 1 MB or less in UTF-8. |
Content Parts (Array Format)
When specifying content as an array, the following part types are available. You can combine text and files in a single message.
| type | Parameter | Description |
|---|---|---|
"text" | text (string) | Text message |
"input_file" | fileId or filepath (string) | Either the fileId of an uploaded file or the filepath of a library file returned by GET /v1/library (exactly one). Up to 20 files total per request |
Request Example
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}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"model": "AGENTIC STAR",
"stream": true,
"messages": [
{
"role": "user",
"content": "Please analyze the sales data"
}
]
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
},
json={
"model": "AGENTIC STAR",
"stream": True,
"messages": [{"role": "user", "content": "Please analyze the sales data"}],
},
stream=True,
)
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "AGENTIC STAR",
stream: true,
messages: [{ role: "user", content: "Please analyze the sales data" }],
}),
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}package main
import (
"bufio"
"bytes"
"encoding/json"
"fmt"
"net/http"
"strings"
)
func main() {
token := "<access_token>" // Access token obtained in Step 1
body, _ := json.Marshal(map[string]interface{}{
"model": "AGENTIC STAR",
"stream": true,
"messages": []map[string]string{
{"role": "user", "content": "Please analyze the sales data"},
},
})
req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions",
bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
line := scanner.Text()
if strings.HasPrefix(line, "data: ") {
data := line[6:]
if data == "[DONE]" { break }
var chunk map[string]interface{}
json.Unmarshal([]byte(data), &chunk)
choices, _ := chunk["choices"].([]interface{})
if len(choices) > 0 {
delta, _ := choices[0].(map[string]interface{})["delta"].(map[string]interface{})
if content, ok := delta["content"].(string); ok {
fmt.Print(content)
}
}
}
}
}Response Headers
| Header | Description |
|---|---|
Content-Type | text/event-stream |
X-Conversation-Id | Conversation ID. For new conversations, a server-generated ID is returned. |
X-Message-Id | The assistant response message ID. |
SSE Response Format
Responses are delivered as SSE events in the following order. Each event is a JSON line prefixed with data:.
data: {"choices":[{"delta":{"role":"assistant"}}]}data: {"choices":[{"delta":{"content":"..."}}]} × Ndata: {"choices":[{"finishReason":"stop"}]}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
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant"},"finishReason":null}]}
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"Analyzing"},"finishReason":null}]}
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":" the sales data."},"finishReason":null}]}
data: {"createdAt":"2026-03-14T10:30:01Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{},"finishReason":"stop"}]}
data: [DONE]
Error Response
Errors before the SSE stream starts are returned in JSON format. Errors during the stream are delivered as SSE chunks.
| Status | Description |
|---|---|
400 | Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input_file parts in a single request, or reportMode other than "with" / "without"). A malformed JSON body (code: "invalid_body"). Or the specified conversationId is archived (code: "conversation_archived"). Or interactionReply is malformed, has an unknown field, is not the ID of a question waiting for an answer in this conversation, or its number is outside the options (code: "invalid_parameter"; param is interactionReply, or the name of a field with interactionReply. in front, such as interactionReply.interactionId), or interactionReply was sent without conversationId (code: "missing_parameter") |
400 | The messages array has no message with the user role (code: "no_user_message") |
400 | personaKey is not in the list returned by GET /v1/personas (code: "invalid_parameter", param: "personaKey") |
400 | The playbook for playbookId does not exist (code: "playbook_not_found") or is disabled (code: "playbook_not_active") |
415 | The body Content-Type is not application/json (code: "unsupported_media_type") |
403 | Missing chat:exec scope, or the specified conversation is a project conversation (code: "project_conversation". Messages cannot be sent to a project conversation) |
404 | The fileId or filepath of the specified input_file was not found (code: "file_not_found") |
409 | The specified conversation is currently being processed (code: "conversation_processing") |
403 | An administrator has not permitted agent mode, and the request uses it (agentMode is true, which is also the default when omitted) (code: "feature_not_permitted", param: "agentMode"). Retry with agentMode set to false, or ask the administrator to permit it |
503 | Feature permissions could not be checked (code: "feature_permissions_unavailable"). Wait and retry |
GET/v1/chat/completions/:conversationId
Reconnect to the SSE stream of a conversation in progress. Use this when the agent is processing a long-running task or to recover after a network disconnection.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | The ID of the conversation to reconnect to |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
stream=True,
)
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
fmt.Println(scanner.Text())
}Response (200 OK)
Reconnects to the SSE stream. The response format is the same as POST /v1/chat/completions. The response headers include X-Conversation-Id and X-Message-Id. For detailed reconnection procedures, see the Streaming Guide.
Error Response
| Status | code | Description |
|---|---|---|
403 | insufficient_scope | The chat:exec scope is missing |
404 | not_found | The conversation was not found, is not in progress, or is not yours (the same applies when conversationId is an empty value) |
POST/v1/chat/completions/:conversationId/cancel
Cancel a conversation in progress. Use this to abort the agent's execution.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | The ID of the conversation to cancel |
Request Body (optional)
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
messageId | string | — | The ID of the message to cancel (UUID). If omitted, cancels the entire conversation. |
Request Example
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"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json"
import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Cancelled: {data['cancelled']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Cancelled: " + data.cancelled);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | The ID of the cancelled conversation (UUID) |
cancelled | boolean | Always true on successful cancellation |
Response Example
{ "conversationId": "550e8400-...", "cancelled": true }
Error Response
| Status | Description |
|---|---|
400 | Invalid conversationId, messageId is not a string, the body is malformed JSON or not a JSON object (code: "invalid_body"), or the conversation is archived (code: "conversation_archived") |
400 | The message of messageId does not belong to the specified conversation (code: "conversation_mismatch") |
400 | The endpoint of this conversation does not support cancellation (code: "unsupported_endpoint"), or cancellation is not enabled in this environment (code: "post_processing_not_enabled") |
415 | The body Content-Type is not application/json (code: "unsupported_media_type") |
403 | Missing chat:exec scope |
404 | Conversation not found, or the message cannot be canceled (code: "message_not_found"). message_not_found is returned in two cases: the message was just sent and could not be canceled after waiting about 10 seconds (sending again in a few seconds cancels it), or the message of messageId does not exist or is not yours (sending again does not cancel it; check messageId) |
404 | The message of messageId is not being processed (it has already finished) (code: "not_processing") |
Conversation Management
List, retrieve message history, delete, and update titles of conversations.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/conversations | List conversations | chat:history |
| GET | /v1/conversations/:conversationId/messages | Get message history | chat:history |
| GET | /v1/conversations/:conversationId/ui-resources/:toolCallId | Get the HTML of a UI resource | chat:exec / a2a:all / mcp:all |
| PATCH | /v1/conversations/:conversationId | Update conversation title | chat:history |
| DELETE | /v1/conversations/:conversationId | Delete a conversation | chat:history |
| POST | /v1/conversations/:conversationId/restore | Restore archived conversation | chat:history |
| POST | /v1/conversations/:conversationId/read | Mark a conversation as read | chat:history |
Note: The Marketplace edition does not require scopes (authentication only).
Archived conversations are deleted automatically once the retention period set by an administrator has passed since they were archived. Their messages, and the attached and artifact files used only by that conversation, are deleted with them. If no retention period is set, they are not deleted.
Operations on archived conversations
Conversations retrieved with mode=archive only support read operations (list / message history) and restoration. The following operations return a 400 error (code: "conversation_archived").
| Operation | Behavior on archived conversations |
|---|---|
GET /v1/conversations?mode=archive | ✅ Allowed |
GET /v1/conversations/:id/messages | ✅ Allowed (messages[].archived: true is added) |
PATCH /v1/conversations/:id | ❌ 400 Archived conversations cannot be modified |
DELETE /v1/conversations/:id | ❌ 400 Archived conversations cannot be deleted via this endpoint |
POST /v1/chat/completions (continuing an existing conversation) | ❌ 400 Cannot send messages to an archived conversation |
POST /v1/chat/completions/:id/cancel | ❌ 400 Cannot cancel an archived conversation |
POST /v1/conversations/:id/restore | ✅ Restore to active |
GET/v1/conversations
List conversations. Supports cursor-based pagination.
Query Parameters
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
limit | integer | — | 50 | Number of items to return (1-100) |
cursor | string | — | — | Cursor for the next page (the cursor value from the previous response) |
order | string | — | "desc" | "asc" or "desc" |
title | string | — | — | Filter by title |
mode | string | — | "active" | "active" (regular conversations) or "archive" (archived conversations). Switching `mode` switches to a different data store, so a `cursor` cannot be carried over |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations",
headers={"Authorization": f"Bearer {token}"},
params={"limit": 10, "order": "desc"},
)
data = response.json()
for conv in data["conversations"]:
print(conv["title"], conv["conversationId"])const params = new URLSearchParams({ limit: "10", order: "desc" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.conversations.forEach((conv) => {
console.log(conv.title, conv.conversationId);
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&order=desc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversations | array | Array of conversation objects |
conversations[].conversationId | string | Unique identifier of the conversation (UUID) |
conversations[].title | string | Conversation title |
conversations[].type | string? | Kind of conversation: "chat" (chat) or "mail" (started from mail). Conversations of project steps are not in the list (their messages can be read by specifying the conversation ID). Not returned with mode=archive |
conversations[].createdAt | string | Creation date and time (ISO 8601) |
conversations[].updatedAt | string | Last updated date and time (ISO 8601) |
conversations[].archived | boolean? | Whether archived. Always true when retrieved via mode=archive. When mode=active returns this field as true, it is only because the conversation remained in archive state but was returned by the active list — usually omitted |
hasMore | boolean | Whether the next page exists |
cursor | string | Cursor for fetching the next page. Included only when hasMore is true |
Response Example
{
"conversations": [
{
"conversationId": "550e8400-e29b-41d4-a716-446655440000",
"title": "Sales data analysis",
"type": "chat",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z"
}
],
"hasMore": true,
"cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | limit is invalid (outside 1-100), mode is not "active" / "archive", order is not "asc" / "desc", cursor is invalid (not a value from the previous response), or title is not a string (for example, it was specified more than once) |
403 | insufficient_scope | The chat:history scope is missing |
502 | upstream_connection_error | The list of conversations could not be retrieved (retry after a while) |
GET/v1/conversations/:conversationId/messages
Retrieve the message history of a specified conversation. Cursor-based pagination is supported. Retrieving it does not mark the conversation as read (the same goes for reading via MCP or A2A). To mark it as read, call Mark a conversation as read.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | Conversation ID (UUID) |
Query Parameters
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
limit | integer | — | 50 | Number of items per page (1-100) |
cursor | string | — | — | Cursor for the next page (the cursor value from the previous response) |
order | string | — | "desc" | "asc" or "desc" |
Request Example
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>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \ -H "Authorization: Bearer <access_token>"
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages",
headers={"Authorization": f"Bearer {token}"},
params={"order": "asc"},
)
messages = response.json()["messages"]
for msg in messages:
print(f"[{msg['sender']}] {msg['text'][:50]}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const { messages } = await response.json();
messages.forEach((msg) => console.log("[" + msg.sender + "] " + msg.text));req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
messages | array | Array of message objects |
messages[].conversationId | string | Conversation ID (UUID) |
messages[].messageId | string | Unique identifier of the message |
messages[].sender | string | Sender. "User" or "AI" |
messages[].text | string | The message body text. If the body is empty, the result (content) of the latest task is returned |
messages[].createdAt | string | Creation date and time (ISO 8601) |
messages[].updatedAt | string | Last updated date and time (ISO 8601) |
messages[].status | object | Message processing status |
messages[].status.processing | boolean | Whether the agent is currently processing |
messages[].status.unfinished | boolean | Whether the agent response was interrupted |
messages[].tasks | array | Array of tasks executed by the agent (see below) |
messages[].deliverables | array | Array of artifacts generated by the agent. Included only when present |
messages[].deliverables[].filename | string | Artifact file name |
messages[].deliverables[].filepath | string | Artifact file path |
messages[].deliverables[].source | string | "agent" (agent-generated) or "user" (user-uploaded) |
messages[].deliverables[].isPrimary | boolean | Whether it is a primary artifact |
messages[].deliverables[].createdAt | string | Creation date and time (ISO 8601 format). An empty string when unknown |
messages[].deliverables[].mimeType | string | MIME type (e.g., "application/pdf", "text/markdown"). "application/octet-stream" when it cannot be determined |
messages[].deliverables[].size | number? | File size (bytes). Omitted when 0 or below |
messages[].files | array? | Array of user-uploaded files. Included only when present for messages with sender: "User" |
messages[].files[].fileId | string | Unique identifier of the file (UUID) |
messages[].files[].mimeType | string | MIME type (e.g., "image/png", "application/pdf") |
messages[].files[].width | number? | Image width in pixels. Only for image files |
messages[].files[].height | number? | Image height in pixels. Only for image files |
messages[].settings | object? | Settings used when the user message (sender: "User") was sent. Only saved items are included, and it is omitted when none are saved. Each item has the same meaning as the item of the same name in sending (POST /v1/chat/completions). Not included in archived messages |
messages[].settings.agentLevel | string? | "default" / "high_performance" |
messages[].settings.agentMode | boolean? | Agent mode |
messages[].settings.privateMode | boolean? | Private mode |
messages[].settings.reportMode | string? | "with" / "without" |
messages[].settings.personaKey | string | null? | Persona key. null when sent without choosing a persona |
messages[].settings.playbookId | string? | Playbook ID |
messages[].settings.skillIds | string[]? | Array of skill IDs |
messages[].archived | boolean? | true only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with GET /v1/conversations?mode=archive |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Task Object
| Field | Type | Description |
|---|---|---|
messageId | string | ID of the message the task belongs to |
conversationId | string | ID of the conversation the task belongs to |
callId | string? | Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call |
actionType | string | Type of task (e.g., tool execution, code generation) |
title | string? | Task title. Omitted when not present |
description | string? | Task description. Omitted when not present |
status | string | Task status. One of: "in_progress" / "completed" / "failed" / "error" / "pending" |
content | string? | Task execution result text. Omitted when not present |
metadata | object? | Auxiliary information that varies by actionType (sub_event_type, url, filepath, etc.). See the Streaming Guide 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. |
interactionId | The ID of the agent's question. It may be absent (for example, for a question asked with a UI component). If this question is still waiting for an answer, you can use it in interactionReply of the next Chat API or MCP request |
draft | A draft made in the chat, together with uiResource. For its shape and how to create it, see Streaming guide — delta.draft |
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.
{
"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.
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
{
"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.
1# First page2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50" \3-H "Authorization: Bearer <access_token>"45# 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>"# First page curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50" \ -H "Authorization: Bearer <access_token>" # Second page (use the cursor returned by the first page) curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \ -H "Authorization: Bearer <access_token>"
If limit is omitted, 50 items are returned. To fetch everything, keep following the cursor until hasMore becomes false.
The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
Items may also be duplicated or skipped across pages if messages are added or removed while you are paging.
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
400 | invalid_parameter | limit is not an integer from 1 to 100, cursor is invalid (not a value from the previous response), or order is not "asc" / "desc" |
403 | insufficient_scope | The chat:history scope is missing |
404 | conversation_not_found | The conversation was not found or is not yours |
GET/v1/conversations/:conversationId/ui-resources/:toolCallId
Retrieves the HTML of a UI resource. Pass the tool_call_id found in SSE delta.uiResource, 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.
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
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>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/ui-resources/chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d \ -H "Authorization: Bearer <access_token>"
response = requests.get(
f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/{conversation_id}/ui-resources/{tool_call_id}",
headers={"Authorization": f"Bearer {token}"},
)
resource = response.json()
html = resource["html"]const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/${conversationId}/ui-resources/${toolCallId}`,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const resource = await response.json();
const html = resource.html;req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/"+conversationID+"/ui-resources/"+toolCallID,
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var resource map[string]interface{}
json.NewDecoder(resp.Body).Decode(&resource)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
toolCallId | string | The UI resource identifier given in the request |
type | string | Always "html" |
origin | string | "first-party" (produced by AGENTIC STAR) or "external" (produced by an external MCP server approved by your administrator) |
mimeType | string | MIME type of the HTML. Normally "text/html;profile=mcp-app" |
html | string | The HTML source |
Response Example
{
"toolCallId": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
"type": "html",
"origin": "first-party",
"mimeType": "text/html;profile=mcp-app",
"html": "<!doctype html><html>...</html>"
}
Error Response
Use code to decide whether a retry makes sense.
| Status | code | Description | Retry |
|---|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000) | No |
400 | invalid_parameter | Invalid toolCallId format | No |
403 | insufficient_scope | None of chat:exec / a2a:all / mcp:all is present | No |
404 | not_found | No such UI resource | No |
404 | conversation_not_found | No such conversation, or it belongs to another user | No |
404 | file_too_large | The HTML exceeds 512KB and cannot be returned | No (permanent failure) |
502 | upstream_api_error | Temporary retrieval failure | Yes |
500 | internal_error | Other errors | Yes |
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
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" }'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "title": "New title" }'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
json={"title": "New title"},
)
data = response.json()
print(f"Updated: {data['title']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({ title: "New title" }),
}
);
const data = await response.json();
console.log("Updated: " + data.title);payload := map[string]string{"title": "New title"}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("PATCH",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | Conversation ID (UUID) |
title | string | Updated title |
type | string | Kind of conversation: "chat", "mail", or "project" (a conversation of a project step) |
createdAt | string | Creation timestamp (ISO 8601) |
updatedAt | string | Last update timestamp (ISO 8601) |
Response Example
{
"conversationId": "550e8400-...",
"title": "New title",
"type": "chat",
"createdAt": "2026-03-14T10:30:00.000Z",
"updatedAt": "2026-03-14T12:00:00.000Z"
}
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
400 | missing_parameter | title is missing |
400 | invalid_title | title is an empty string, is not a string, or exceeds 200 characters |
400 | invalid_body | The body is malformed JSON |
400 | conversation_archived | The conversation is archived |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
403 | insufficient_scope | The chat:history scope is missing |
404 | conversation_not_found | The conversation was not found or is not yours |
DELETE/v1/conversations/:conversationId
Delete a conversation. Of the files attached to its messages and its artifact files, those not used by any other conversation are deleted too (they no longer appear in GET /v1/files).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | Conversation ID (UUID) |
Request Example
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \2-H "Authorization: Bearer <access_token>"curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Deleted: {data['deleted']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Deleted: " + data.deleted);req, _ := http.NewRequest("DELETE",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | ID of the deleted conversation (UUID) |
deleted | boolean | Always true on successful deletion |
Response Example
{ "conversationId": "550e8400-...", "deleted": true }
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
400 | conversation_archived | The conversation is archived. Use POST /v1/conversations/:id/restore to restore it |
403 | insufficient_scope | The chat:history scope is missing |
404 | conversation_not_found | The conversation was not found or is not yours |
409 | conversation_processing | The conversation cannot be deleted because it is currently being processed |
409 | project_conversation | A project conversation. Project conversations cannot be deleted |
409 | claw_bound_conversation | A conversation tied to a Claw schedule. First delete the Claw schedule tied to this conversation in the app |
409 | legal_hold | A conversation under legal hold. It cannot be deleted until an administrator releases the hold |
503 | claw_binding_unverified | Whether the conversation is tied to a Claw schedule could not be verified. Retry after a while |
POST/v1/conversations/:conversationId/restore
Restore an archived conversation back to active. After restoration, the conversation can be edited, continued, and deleted just like a regular conversation.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | ID of the archived conversation (UUID) |
Request Example
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>"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"Restored: {data['restored']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("Restored: " + data.restored);req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
conversationId | string | ID of the restored conversation (UUID) |
restored | boolean | Always true on successful restoration |
Response Example
{ "conversationId": "550e8400-...", "restored": true }
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
403 | insufficient_scope | The chat:history scope is missing |
404 | conversation_not_found | The conversation does not exist in the archive, or is already active (not distinguished from the archived state) |
POST/v1/conversations/:conversationId/read
Marks a conversation as read. Reading the messages of a conversation through the API (REST, MCP, or A2A) does not mark it as read, so call this when you want to record that it was read. The read position never moves back (specifying an earlier message does not move it before where it is).
In the SaaS edition, a personal schedule or Claw outside projects may be stopped when it has finished 3 or more runs in a row since it was last read and the oldest of them is 14 or more days ago (project sweeps are not affected). If you read the results through the API and do not want it to stop, mark the conversation as read with this API. Opening the conversation in the screen also marks it as read.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
conversationId | string | 必須 | Conversation ID (UUID) |
Request Body (optional)
The body can be omitted. When you send one, use Content-Type: application/json.
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
messageId | string | — | ID of the last message you read. If omitted, the conversation is marked as read up to its latest message at that moment (specify it to avoid marking messages that arrived while you were reading) |
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/read \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{"messageId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/read \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"messageId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'Response (204 No Content)
There is no body.
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_conversation_id | conversationId is the all-zero UUID (00000000-0000-0000-0000-000000000000). This value is not accepted |
400 | invalid_parameter | messageId is empty or not a string |
400 | invalid_body | The body is not a JSON object |
400 | conversation_archived | The conversation is archived |
415 | unsupported_media_type | The body is not application/json |
403 | insufficient_scope | The chat:history scope is missing |
404 | conversation_not_found | The conversation does not exist or is not yours |
404 | message_not_found | The messageId is not in that conversation |
File Management
Upload, retrieve, and delete files.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/files | List files | chat:file |
| POST | /v1/files | Upload a file | chat:file |
| GET | /v1/files/:fileId/content | Download a file | chat:file |
| DELETE | /v1/files/:fileId | Delete a file | chat:file |
Note: The Marketplace edition does not require scopes (authentication only).
POST/v1/files
Upload a file.
Request Body (multipart/form-data)
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
file | file | 必須 | The file to upload. Maximum size 512 MB. |
filename | string | 必須 | File name |
Request Example
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"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/files \ -H "Authorization: Bearer <access_token>" \ -F "file=@report.pdf" \ -F "filename=report.pdf"
import requests
with open("report.pdf", "rb") as f:
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files",
headers={"Authorization": f"Bearer {token}"},
files={"file": f},
data={"filename": "report.pdf"},
)
data = response.json()
print(data["fileId"])const formData = new FormData();
formData.append("file", file); // File object from input
formData.append("filename", "report.pdf");
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files",
{
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
}
);
const data = await response.json();
console.log(data.fileId);file, _ := os.Open("report.pdf")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "report.pdf")
io.Copy(part, file)
writer.WriteField("filename", "report.pdf")
writer.Close()
req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files",
body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())Response Fields (201 Created)
| Field | Type | Description |
|---|---|---|
fileId | string | Unique identifier of the file (UUID) |
filename | string | File name |
bytes | integer | File size (bytes) |
createdAt | string | Creation date and time (ISO 8601) |
width | integer | Image width (pixels). Only for image files |
height | integer | Image height (pixels). Only for image files |
Response Example
{
"fileId": "550e8400-e29b-41d4-a716-446655440001",
"filename": "report.pdf",
"bytes": 1048576,
"createdAt": "2026-03-14T10:30:00.000Z"
}
Error Response
| Status | code | Description |
|---|---|---|
400 | missing_parameter | The file or filename parameter is missing |
400 | file_too_large | The file size exceeds 512 MB |
400 | invalid_parameter | The uploaded image file is corrupted or invalid |
415 | unsupported_media_type | The body is not multipart/form-data, or the file type is not accepted (including extensions and MIME types the environment has decided not to accept) |
403 | insufficient_scope | The chat:file scope is missing |
403 | feature_not_permitted | An administrator has not permitted file uploads |
503 | feature_permissions_unavailable | The feature permissions could not be checked. Retry after a while |
GET/v1/files
List files. Cursor-based pagination is supported.
Query Parameters
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
limit | integer | — | 50 | Number of items per page (1-100) |
cursor | string | — | — | Cursor for the next page (the cursor value from the previous response) |
order | string | — | "desc" | "asc" (oldest first) or "desc" (newest first). Sorted by the file update time |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?order=desc \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?order=desc \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files",
headers={"Authorization": f"Bearer {token}"},
params={"order": "desc"},
)
files = response.json()["files"]
for file in files:
print(f"{file['filename']} ({file['bytes']} bytes)")const params = new URLSearchParams({ order: "desc" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.files.forEach((file) => {
console.log(file.filename + " (" + file.bytes + " bytes)");
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?order=desc",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
files | array | Array of file objects |
files[].fileId | string | Unique identifier of the file (UUID) |
files[].filename | string | File name |
files[].bytes | integer | File size (bytes) |
files[].createdAt | string | Creation date and time (ISO 8601) |
files[].width | integer | Image width (pixels). Only for image files |
files[].height | integer | Image height (pixels). Only for image files |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"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.
1# First page2curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \3-H "Authorization: Bearer <access_token>"45# 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>"# First page curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc" \ -H "Authorization: Bearer <access_token>" # Second page (use the cursor returned by the first page) curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files?limit=50&order=desc&cursor=<cursor>" \ -H "Authorization: Bearer <access_token>"
If limit is omitted, 50 items are returned. To fetch everything, keep following the cursor until hasMore becomes false.
The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
Items may also be duplicated or skipped across pages if files are added or removed while you are paging.
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | limit is not an integer from 1 to 100 |
400 | invalid_parameter | cursor is invalid (not a value from the previous response) |
400 | invalid_parameter | order is not "asc" / "desc" |
403 | insufficient_scope | The chat:file scope is missing |
GET/v1/files/:fileId/content
Download a file.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
fileId | string | 必須 | File ID (UUID) |
Request Example
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.pdfcurl https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \ -H "Authorization: Bearer <access_token>" \ -o downloaded_file.pdf
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
headers={"Authorization": f"Bearer {token}"},
stream=True,
)
with open("downloaded_file.pdf", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)const fs = require("fs");
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const buffer = await response.arrayBuffer();
fs.writeFileSync("downloaded_file.pdf", new Uint8Array(buffer));req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
file, _ := os.Create("downloaded_file.pdf")
defer file.Close()
io.Copy(file, resp.Body)Response (200 OK)
The file binary data is returned as a stream.
| Response Header | Description |
|---|---|
Content-Type | MIME type of the file |
Content-Length | File size (bytes) |
Content-Disposition | attachment; filename="filename"; filename*=UTF-8''<percent-encoded UTF-8 filename> |
When saving the file, use the name in filename* (the UTF-8 name, percent-encoded) if it is present; otherwise use filename. For a name that contains characters such as Japanese, filename is a substitute name, and the original name is only in filename*. For example, for 売上.pdf ("sales.pdf" in Japanese), the header looks like this (the substitute name in filename is only an example).
Content-Disposition: attachment; filename="file_1731650000000.pdf"; filename*=UTF-8''%E5%A3%B2%E4%B8%8A.pdf
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | fileId has an invalid format |
403 | insufficient_scope | The chat:file scope is missing |
404 | file_not_found | The file was not found |
503 | service_unavailable | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |
DELETE/v1/files/:fileId
Delete a file. Deleting a conversation also deletes the files used only by that conversation (see Delete a conversation).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
fileId | string | 必須 | File ID (UUID) |
Request Example
1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \2-H "Authorization: Bearer <access_token>"curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
print(f"File deleted: {data['deleted']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
{
method: "DELETE",
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
console.log("File deleted: " + data.deleted);req, _ := http.NewRequest("DELETE",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
fileId | string | ID of the deleted file (UUID) |
deleted | boolean | Always true on successful deletion |
Response Example
{ "fileId": "550e8400-e29b-41d4-a716-446655440001", "deleted": true }
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | fileId has an invalid format |
403 | insufficient_scope | The chat:file scope is missing |
404 | file_not_found | The file was not found |
Artifact Retrieval
Retrieve artifact files generated by the agent.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/files/proxy | Get an artifact file | chat:exec / a2a:all / mcp:all |
Note: The Marketplace edition does not require scopes (authentication only).
GET/v1/files/proxy
Download an artifact file by specifying the path obtained from deliverables[].filepath in the message history.
chat:exec / a2a:all / mcp:all is sufficient. Artifacts obtained through an A2A artifact or an MCP tool response can be downloaded here with the scope of that same channel.
Files in project execution results and review request evidence (files[].filepath) are not downloaded with this endpoint. Use Get the content of a project file (GET /v1/projects/{projectId}/files/content) instead.
Query Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
path | string | 必須 | Artifact file path (obtained from deliverables[].filepath in the message history) |
version_id | string | — | ID of a version of the file (versionId from the file library version list, GET /v1/library/versions). The current version if omitted |
Request Example
filepath is the value of messages[].deliverables[].filepath from Get message history.
1FILEPATH='<filepath>'23curl --get "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy" \4--data-urlencode "path=$FILEPATH" \5-H "Authorization: Bearer <access_token>" \6-o artifact.xlsxFILEPATH='<filepath>' curl --get "https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy" \ --data-urlencode "path=$FILEPATH" \ -H "Authorization: Bearer <access_token>" \ -o artifact.xlsx
import requests
filepath = "<filepath>"
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy",
headers={"Authorization": "Bearer " + token},
params={"path": filepath},
stream=True,
)
with open("artifact.xlsx", "wb") as f:
for chunk in response.iter_content(chunk_size=8192):
f.write(chunk)const filepath = "<filepath>";
const params = new URLSearchParams({
path: filepath,
});
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const blob = await response.blob();import (
"io"
"net/http"
"net/url"
"os"
)
filepath := "<filepath>"
req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/files/proxy?"+url.Values{"path": {filepath}}.Encode(),
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
out, _ := os.Create("artifact.xlsx")
defer out.Close()
io.Copy(out, resp.Body)Response (200 OK)
The artifact file binary data is returned as a stream.
| Response Header | Description |
|---|---|
Content-Type | MIME type of the file |
Content-Length | File size (bytes) |
Error Response
| Status | code | Description |
|---|---|---|
400 | missing_parameter | The path parameter is missing |
400 | invalid_parameter | The path format is invalid (no UUID-shaped segment) |
403 | insufficient_scope | None of chat:exec / a2a:all / mcp:all is held |
404 | not_found | The file was not found (if the storage response carries another code, that code is returned) |
500 | unknown | Unknown error from the storage |
500 | storage_forbidden | Access to the storage was denied. Contact your administrator |
500 | rejected | The storage rejected the request. Contact your administrator |
503 | rate_limited | The storage is temporarily busy. Retry after a while |
503 | transient | The storage is temporarily unavailable. Retry after a while |
503 | service_unavailable | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator |
Library
Lists the user's library files (uploaded files and artifacts generated by the agent) across conversations. A returned filepath can be used to attach a file via Chat input_file or to download it through the artifact endpoint (GET /v1/files/proxy).
Endpoints
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/library | List library files | chat:exec |
| GET | /v1/library/versions | List the versions of a library file | chat:exec |
GET/v1/library
Retrieves the list of library files. Supports cursor-based pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Number of items to retrieve (1–100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
search | string | — | Filter by file name (partial match) |
source | string | — | Filter by "agent" (agent-generated) or "user" (user-uploaded) |
order | string | "desc" | "asc" or "desc" |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library?source=agent&limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library?source=agent&limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/library",
headers={"Authorization": f"Bearer {token}"},
params={"source": "agent", "limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/library" + "?source=agent&limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library?source=agent&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
files | array | Array of library file objects |
files[].filename | string | File name |
files[].filepath | string | File path (used for Chat input_file attachment or download via GET /v1/files/proxy) |
files[].source | string | "agent" (agent-generated) or "user" (user-uploaded) |
files[].createdAt | string | Creation timestamp (ISO 8601) |
files[].updatedAt | string | Last update timestamp (ISO 8601) |
files[].mimeType | string? | MIME type. Omitted when it cannot be determined |
files[].size | number? | File size in bytes. Omitted when unavailable |
files[].conversationId | string? | Associated conversation ID. Included only when the artifact is tied to a conversation |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"files": [
{
"filename": "report.xlsx",
"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
"source": "agent",
"createdAt": "2026-03-14T10:30:00.000Z",
"updatedAt": "2026-03-14T10:30:00.000Z",
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"size": 20480,
"conversationId": "550e8400-e29b-41d4-a716-446655440000"
}
],
"hasMore": false
}
Error Responses
| Status | Description |
|---|---|
400 | Invalid limit (out of 1–100 range), cursor, source (other than "agent" / "user"), order (other than "asc" / "desc"), or search (not a string) |
403 | Missing chat:exec scope |
GET/v1/library/versions
Gets the versions of one library file, newest first. All versions are returned, and hasMore is always false. Get the content of a version by passing versionId as version_id of the artifact endpoint (GET /v1/files/proxy). For a file without version records, versions is an empty array and currentVersionId is null.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
path | string | — | Required. The file path (filepath from GET /v1/library) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions",
headers={"Authorization": f"Bearer {token}"},
params={"path": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions" + "?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/library/versions?path=/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
filepath | string | The file path |
currentVersionId | string | null | ID of the current version. null when there are no versions |
versions | array | Array of versions (newest first) |
versions[].versionId | string | null | ID of the version |
versions[].size | number | null | Size (bytes) |
versions[].createdAt | string | null | When the version was made (ISO 8601) |
versions[].isCurrent | boolean | Whether it is the current version |
hasMore | boolean | Always false |
Response Example
{
"filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.xlsx",
"currentVersionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
"versions": [
{
"versionId": "3b8a1c5e-7d2f-4e9a-a6c0-1f4d8b2e5a79",
"size": 20480,
"createdAt": "2026-03-14T10:30:00.000Z",
"isCurrent": true
},
{
"versionId": "c4d9e2f1-0a3b-4c6d-8e7f-5a1b2c3d4e6f",
"size": 18944,
"createdAt": "2026-03-13T08:00:00.000Z",
"isCurrent": false
}
],
"hasMore": false
}
Error Responses
| Status | Description |
|---|---|
400 | path is missing or empty (code: "invalid_parameter") |
403 | Missing chat:exec scope |
404 | The file was not found, or it is not yours (code: "not_found") |
502 | An internal temporary error occurred in the service (code: "upstream_connection_error"). Retry after a while |
Common Rules for Agents, Playbooks, and Skills
These rules are common to the APIs that read, create, change, delete, and copy Agents, Playbooks, and Skills. They cannot be called with a system integration token (calling returns 403 Forbidden (forbidden)).
| Operation | Scope | Target | When out of scope |
|---|---|---|---|
| Read | assets:read (the lists of skills and playbooks can also be called with chat:exec) | Your own and published ones | Another user's private ones and ones that do not exist return 404 Not Found (agent_not_found, playbook_not_found, skill_not_found) |
| Create / copy | assets:write | — | — |
| Update | assets:write | Your own only | Another user's returns 404 Not Found |
| Delete | assets:delete | Your own only (a system administrator can also delete playbooks and skills published by other users) | Another user's returns 404 Not Found |
- To change another user's resource, copy it to your own and change the copy.
- When changing, put the
digestfrom the get API intobaseDigestand send it. If another change was made after you got it,409 Conflict(stale_base) is returned. Get it again and resend. - A JSON body can be up to 3 MiB. A larger body returns
413 Payload Too Large(body_too_large). For the APIs that send skill files, see the limit in the description of each API. - The Agent APIs return
403 Forbidden(sso_required) for a token of a user who does not sign in with SSO.
Resends are handled as follows.
| API | What identifies a resend | Resending with the same value |
|---|---|---|
| Create | — | Another one is created. If the response did not arrive, check whether it was created by using the ID and createdAt in the list before sending again |
| Copy | Idempotency-Key header (optional) | The first copy is returned and no other is created. Without it, sending again creates another one, as with create (except copying a registered Agent in the Marketplace edition; see the description of copying an Agent) |
Edit skill documents (PATCH /v1/skills/:skillId/files) | The Idempotency-Key header (optional) | Returns the version created by the first request without creating a new version |
Publishing Approval for Skills and Playbooks
When the tenant administrator requires approval to share skills and playbooks, sending isShared: true does not share it; it waits for publishing approval instead (the same as "Request publishing" on the screen). The administrator approves or returns it in the admin console. Whether approval is required cannot be read through the API. Check whether it was shared or is waiting for approval with isShared and shareRequestStatus in the response.
The following request status fields are included in the list and get responses of your own skills and playbooks, and in the responses of creating, changing, and copying them. They are not included in the shared lists or when getting an item shared by another user. However, sharePendingListing is not included in the skill of the response for editing skill documents (get the skill to read it).
| Field | Type | Description |
|---|---|---|
shareRequestStatus | string | null | "pending" (awaiting approval), "rejected" (returned), or null (not requested) |
shareRequestNote | string | null | Note for the request |
shareReviewNote | string | null | Comment from the administrator (for example, when it was returned) |
shareRequestedAt | string | null | When it was requested (ISO 8601) |
sharePendingVersionId | string | null | Skills only. ID of the version awaiting approval |
sharePendingListing | object | null | Skills only. Category and tags awaiting approval. The fields recorded for the pending change (category, tags) are included, even when changed back to the shared values before approval. null when there are none |
- Note for the request (
shareRequestNote): Can be sent when creating a skill, replacing the files of a skill, changing the settings of a skill, and creating or changing a playbook. Up to 2000 characters, not counting leading and trailing whitespace (a longer note returns400 Bad Request(invalid_parameter)). An empty string, whitespace only, or null is the same as not sending it. The note is kept only when a request is made. It is not used when no approval was needed (a tenant that does not require approval). You can tell which happened fromshareRequestStatusandisSharedin the response. - The note alone cannot be changed: Sending a different note to an item awaiting approval without changing its content returns
400 Bad Request(invalid_parameter). To change the note, withdraw the request and request again. The same note as now is accepted as a resend. - Withdrawing: Send
isShared: falseto an item awaiting approval (with Change Skill Settings for a skill, and Change Playbook for a playbook). - New versions of a shared skill: In a tenant where publishing approval is enabled, changing the files of a shared skill makes the new version wait for approval, and the previous version is used until it is approved.
- Category and tags of a shared skill: In a tenant where publishing approval is enabled, changing the category or tags of a shared skill (with Change Skill Settings) makes the new values wait for approval, and the skill's
categoryandtagskeep the previous values until it is approved. The values awaiting approval are insharePendingListing. IfisShared: falseis sent in the same call, the change is applied at once without approval and the skill stops being shared. - Content of a shared playbook: In a tenant where publishing approval is enabled, changing the content of a shared playbook (name, description, category, tags, and steps) keeps it shared (
isSharedstaystrue) and makes the changed content a request (shareRequestStatusis"pending"). Until it is approved, other users see the approved content (in the shared list, Get, and Copy). Your own Get, and your own Agents and chats, use the changed content. Changing it back to the shared content withdraws the request. After the request is sent back, sendingisShared: true(even without changing the content) requests again.
Agents
Agents that are placed on project steps and run are handled as library resources. An Agent ID (agentId) is a different value from the placement ID assigned when the Agent is placed in a project.
Endpoints
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/agents | List your Agents | assets:read |
| GET | /v1/agents/shared | List shared Agents | assets:read |
| GET | /v1/agents/:agentId | Get an Agent | assets:read |
| POST | /v1/agents | Create an Agent | assets:write |
| PATCH | /v1/agents/:agentId | Edit an Agent | assets:write |
| DELETE | /v1/agents/:agentId | Delete an Agent | assets:delete |
| POST | /v1/agents/:agentId/copy | Copy a shared Agent as your own Agent | assets:write |
GET/v1/agents
Lists your Agents in descending order of last update (newest first). Supports cursor-based pagination. The list of shared Agents (GET /v1/agents/shared) uses the same query parameters and response.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
q | string | — | Filter by part of the name, description, or goal (up to 100 characters) |
limit | integer | 50 | Number of items per page (1-100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents?q=order&limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents?q=order&limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents",
headers={"Authorization": f"Bearer {token}"},
params={"q": "order", "limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents" + "?q=order&limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents?q=order&limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
agents | array | Array of Agent objects. Each item is the same as the Get Agent response except for digest |
hasMore | boolean | Whether there is a next page |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"agents": [
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "Order data import",
"description": "Create order data from order emails",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "Create an order data table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
"inputFiles": [
{
"type": "blob",
"filepath": "/path/to/orders-template.xlsx",
"filename": "orders-template.xlsx"
}
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 1,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"adminStop": null
}
],
"hasMore": false
}
Error Responses
| Status | Description |
|---|---|
400 | Invalid limit (out of 1–100 range), cursor, or q (not a string, or longer than 100 characters) (code is invalid_parameter) |
403 | The assets:read scope is missing (code is insufficient_scope), called with a system integration token (code is forbidden), or the user does not sign in with SSO (code is sso_required) |
GET/v1/agents/shared
Lists shared Agents (including those you shared yourself). An Agent shared only with organizations is listed only for users in those organizations. The query parameters, response, and errors are the same as for listing your own Agents.
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared?limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared?limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/shared?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)GET/v1/agents/:agentId
Gets an Agent. You can get your own Agents and shared Agents.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
agentId | string | 必須 | Agent ID (UUID) |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
agentId | string | Agent ID (UUID) |
name | string | null | Name |
description | string | null | Description |
ownerUserId | string | null | User ID of the owner |
isShared | boolean | null | Whether the Agent is shared |
shareScope | string | null | Who the Agent is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations) |
shareOrganizations | array | null | Array of the organization codes it is shared with. Used when shareScope is "organizations" |
runtimeKind | string | null | Kind of runtime. "autonomous", or "marketplace" for a registered Agent of the Marketplace edition |
marketplaceAgentId | string | null | ID of the registered Agent in the Marketplace edition. null otherwise |
spec | object | Definition of the Agent |
spec.goal | string | null | Goal (instructions) |
spec.guardrail | string | null | Guardrail |
spec.skills | array | Skills to use |
spec.skills[].skillId | string | null | Skill ID |
spec.skills[].name | string | null | Skill name |
spec.skills[].versionId | string | null | ID of the pinned skill version. null if not pinned, in which case the version at that time is always used |
spec.playbookId | string | null | ID of the playbook to use |
spec.inputFiles | array | Input files |
spec.inputFiles[].type | string | null | Kind of input file. "blob" for library files. An Agent created from a scheduled job may have "git" or "upload" |
spec.inputFiles[].filepath | string | null | File path. For "blob", the same form as the filepath from GET /v1/library. For "git" and "upload", the stored reference with a leading /, which is not a library path |
spec.inputFiles[].filename | string | null | File name |
spec.agentLevel | string | null | "default" or "high_performance" |
spec.orgId | string | null | Code of the organization used at run time |
spec.jobRole | string | null | Code of the job type used at run time |
spec.agentConfig | object | null | Not used at present (even if it has a value, the value is not used) |
spec.exposureConsent | object | null | Not used at present (even if it has a value, the value is not used) |
projectCount | number | null | Number of projects where this Agent is placed (placements in deleted projects are not counted) |
copyCount | number | null | Number of times it has been copied |
adminStop | object | null | When an administrator has stopped the Agent: where it was stopped from, why, and when. null if it is not stopped. Returned by List and Get |
adminStop.source | string | null | Where it was stopped from. "aster" (an AGENTIC STAR administrator), or a connected service: "agent365" or "aws" |
adminStop.reasonCode | string | null | The kind of reason. "admin" (an administrator stopped it), "remote_stopped" (it was stopped in the connected service), or "remote_unreachable" (the connected service cannot be reached) |
adminStop.reason | string | null | The reason text. Present only for your own Agents (null for another user's Agent) |
adminStop.stoppedAt | string | null | When it was stopped (ISO 8601) |
createdAt | string | null | Creation time (ISO 8601) |
updatedAt | string | null | Last update time (ISO 8601) |
digest | string | Value to send as baseDigest when editing the Agent. It is made from the name, description, sharing, sharing scope, organizations it is shared with, and definition, and does not change with the number of projects, the copy count, or timestamps |
Response Example
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "Order intake",
"description": "Creates order data from order emails",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "Create an order table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{ "skillId": "cb62d540-5439-4748-99f0-961b8de91a78", "name": "order-parser", "versionId": null }
],
"playbookId": "8af8d6be-2885-446d-9e36-ee9dcf1fe1ba",
"inputFiles": [
{ "type": "blob", "filepath": "/path/to/orders-template.xlsx", "filename": "orders-template.xlsx" }
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 1,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "1aKrerEIdHNpFSBa9TkuXycB1Q6oD2NUX18-uGPiPLg"
}
Error Responses
| Status | Description |
|---|---|
400 | agentId is not a UUID (code is invalid_parameter) |
403 | The assets:read scope is missing (code is insufficient_scope), called with a system integration token (code is forbidden), or the user does not sign in with SSO (code is sso_required) |
404 | The Agent does not exist, or it is another user's private Agent (code is agent_not_found) |
POST/v1/agents
Creates an Agent.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name (up to 255 characters; cannot be empty) |
description | string | — | Description (up to 5000 characters) |
isShared | boolean | — | Whether to share it. Private if omitted |
spec | object | Yes | Definition of the Agent |
spec.goal | string | Yes | Goal (instructions). Up to 5000 characters. Cannot be only whitespace |
spec.guardrail | string | — | Guardrail. Up to 5000 characters |
spec.skills | array | — | Skills to use, in the form [{ skillId, versionId? }]: up to 10 of your own skills or shared skills (active ones). With versionId, that version is pinned; if omitted or null, the version at that time is always used. For a skill of another user, versionId must be a version that has been shared (the range returned by List Skill Versions). You can send the spec.skills from the get API as is (name is ignored). The same skill cannot be specified twice |
spec.playbookId | string | — | ID of the playbook to use. Your own playbooks only |
spec.inputFiles | array | — | Input files, in the form [{ type, filepath, filename? }]: up to 10. type is "blob" (a file in your library; filepath is the filepath from GET /v1/library). An Agent created from a scheduled job may have "git" or "upload", and the values from the get API can be sent as is. filepath cannot be empty after removing leading /. filename is a string of up to 255 characters, or null. At run time, the attached input files are passed as they are (they are not dropped even if they are not the project owner's files) |
spec.agentLevel | string | — | "default" or "high_performance" |
spec.orgId | string | — | Code of the organization used at run time (up to 255 characters) |
spec.jobRole | string | — | Code of the job type used at run time (up to 255 characters) |
Sending null for description or for a field of spec other than goal is the same as omitting it (spec.skills and spec.inputFiles become empty).
spec.skillIds and spec.skillVersions are not accepted (sending them returns 400, invalid_parameter). Specify skills with spec.skills.
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "name": "Order data import",6 "description": "Create order data from order emails",7 "spec": {8 "goal": "Create an order data table from the order emails received.",9 "guardrail": "Do not send anything to external services.",10 "skills": [11 {12 "skillId": "cb62d540-5439-4748-99f0-961b8de91a78"13 }14 ],15 "agentLevel": "default"16 }17}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Order data import",
"description": "Create order data from order emails",
"spec": {
"goal": "Create an order data table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"
}
],
"agentLevel": "default"
}
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents",
headers={"Authorization": f"Bearer {token}"},
json={'name': 'Order data import', 'description': 'Create order data from order emails', 'spec': {'goal': 'Create an order data table from the order emails received.', 'guardrail': 'Do not send anything to external services.', 'skills': [{'skillId': 'cb62d540-5439-4748-99f0-961b8de91a78'}], 'agentLevel': 'default'}},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Order data import", "description": "Create order data from order emails", "spec": {"goal": "Create an order data table from the order emails received.", "guardrail": "Do not send anything to external services.", "skills": [{"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"}], "agentLevel": "default"}}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"name": "Order data import", "description": "Create order data from order emails", "spec": {"goal": "Create an order data table from the order emails received.", "guardrail": "Do not send anything to external services.", "skills": [{"skillId": "cb62d540-5439-4748-99f0-961b8de91a78"}], "agentLevel": "default"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the created Agent in the same form as the Get Agent response (without adminStop; check it with List or Get), plus removedSkillIds (string[]): the IDs of skills that could no longer be used (deleted, deactivated, no longer shared, or the pinned version does not exist or is not shared) and were removed when saving. Empty if none were removed.
Response Example
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "Order data import",
"description": "Create order data from order emails",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "Create an order data table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": null,
"inputFiles": [],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
"removedSkillIds": []
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | name or spec is missing, name, description, or isShared has the wrong type or length, name is only whitespace, spec is not an object, spec.playbookId is not a UUID, spec.skills has the wrong form (skillId or versionId is not a UUID, the same skill twice, and so on), or spec.skillIds or spec.skillVersions was sent |
400 | invalid_spec | spec.goal is missing or only whitespace, a string field in spec has the wrong type or length, spec.agentLevel is not an allowed value, spec.inputFiles has the wrong form (type other than "blob", "git", or "upload", an empty filepath, a filename over 255 characters, and so on), or more than 10 skills or input files |
400 | playbook_not_found | spec.playbookId is not one of your playbooks |
400 | skill_not_found | A skill in spec.skills is neither your own skill nor an active shared skill |
400 | version_not_found | A versionId in spec.skills is not a version of that skill, or is a version of another user's skill that is not shown (one not returned by List Skill Versions) |
400 | file_not_found | A file in spec.inputFiles whose type is "blob" is not in your library |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
403 | sso_required | The user does not sign in with SSO |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The body Content-Type is not application/json |
PATCH/v1/agents/:agentId
Edits one of your Agents. Only the fields you send are changed.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
agentId | string | 必須 | Agent ID (UUID) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
baseDigest | string | Yes | The digest from the Get Agent response |
name | string | — | Name (up to 255 characters; cannot be empty) |
description | string | — | Description (up to 5000 characters; cannot be an empty string, only whitespace, or null) |
isShared | boolean | — | Whether to share it |
shareScope | string | — | Who the Agent is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations) |
shareOrganizations | array | — | Organization codes it is shared with (up to 20, each up to 255 characters; surrounding whitespace is removed and duplicates are merged). Sending it replaces the whole list. At least one is required when the item is shared with the scope "organizations", and when it is sent together with shareScope "organizations" |
spec | object | — | Definition of the Agent. Only the fields you send are overlaid on the current definition (skills and inputFiles are replaced as whole arrays). The fields are the same as when creating an Agent. Sending null for a field removes it (skills and inputFiles become empty). goal cannot be removed |
Send at least one of name, description, isShared, shareScope, shareOrganizations, and spec.
When you change spec, the playbook and input files the definition points to, and the skills you newly add (including skills whose version you change), are checked, including fields you did not send. 400 is returned unless the playbook is your own, the skills are active and are your own or shared, and the input files are in your library. Skills the Agent already had are not refused with 400 even if they can no longer be used: they are removed when saving and returned in removedSkillIds. A copied Agent may point to another user's playbook, skills, or input files (a skill that is shared and active still points to the original skill after copying, and it can no longer be used once its sharing is stopped). In that case, change them to your own.
Request Example
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",6 "description": "Create an order data table from order emails"7}'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs",
"description": "Create an order data table from order emails"
}'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
headers={"Authorization": f"Bearer {token}"},
json={'baseDigest': 'GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs', 'description': 'Create an order data table from order emails'},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs", "description": "Create an order data table from order emails"}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"baseDigest": "GzMT6fWNUwA2FM-LYhLjEaaciV5AUkkvk5cAyupcmFs", "description": "Create an order data table from order emails"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
Returns the edited Agent (with a new digest) in the same form as the Get Agent response (without adminStop; check it with List or Get), plus removedSkillIds (string[]): the IDs of skills that could no longer be used (deleted, deactivated, no longer shared, or the pinned version does not exist or is not shared) and were removed when saving. Empty if none were removed.
Response Example
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"name": "Order data import",
"description": "Create an order data table from order emails",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "Create an order data table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": null,
"inputFiles": [],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "NhoPOFZIlKaF-GPh9VCRdVUAFqIZpE3OX1wt-BKdtu0",
"removedSkillIds": []
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | agentId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name, description, or isShared has the wrong type or length, name is only whitespace, description was set to an empty string, only whitespace, or null, spec is not an object, spec.playbookId is not a UUID, spec.skills has the wrong form (the same skill twice, and so on), or spec.skillIds or spec.skillVersions was sent |
400 | invalid_spec | spec.goal was set to null or only whitespace, a string field in spec has the wrong type or length, spec.agentLevel is not an allowed value, spec.inputFiles has the wrong form (type other than "blob", "git", or "upload", an empty filepath, a filename over 255 characters, and so on), or more than 10 skills or input files |
400 | playbook_not_found | The playbook in the definition is not one of your playbooks |
400 | skill_not_found | A skill you newly added (including a skill whose version you changed) is neither your own skill nor an active shared skill (skills the Agent already had are removed when saving and returned in removedSkillIds) |
400 | version_not_found | The versionId of a skill you newly added or whose version you changed is not a version of that skill, or is a version of another user's skill that is not shown (one not returned by List Skill Versions). A pin kept without changing its version that can no longer be used is removed when saving and returned in removedSkillIds |
400 | file_not_found | An input file in the definition whose type is "blob" is not in your library |
400 | runtime_not_allowed | A registered Agent of the Marketplace edition cannot be edited |
400 | invalid_share_scope | shareScope is not "all" or "organizations" |
400 | invalid_share_organizations | shareOrganizations is not an array, has 21 or more items, or has a value that is not a string, is empty or only whitespace, or is 256 characters or longer |
400 | share_organizations_required | "organizations" was sent for shareScope with an empty shareOrganizations, or the item is shared (isShared is true in the sent or current value) while the scope is "organizations" and there is no organization (the sent and current values are combined) |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
403 | sso_required | The user does not sign in with SSO |
404 | agent_not_found | The Agent does not exist, or it is another user's Agent |
409 | stale_base | The Agent has changed since you got it |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The body Content-Type is not application/json |
DELETE/v1/agents/:agentId
Deletes one of your Agents. The deleted Agent is removed from the projects where it was placed, and the sweeps of those placements stop.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
agentId | string | 必須 | Agent ID (UUID) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
force | string | "false" | Specify "true" to delete even if the Agent is placed in projects. A value other than "true" / "false" returns 400 |
Request Example
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false" \2-H "Authorization: Bearer <access_token>"curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b",
headers={"Authorization": f"Bearer {token}"},
params={"force": "false"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b" + "?force=false",
{
method: "DELETE",
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
{
"agentId": "17be0242-a5d0-4db7-92e5-f97a05abae2b",
"deleted": true
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | agentId is not a UUID, or force is not "true" / "false" |
403 | insufficient_scope | The assets:delete scope is missing |
403 | forbidden | Called with a system integration token |
403 | sso_required | The user does not sign in with SSO |
404 | agent_not_found | The Agent does not exist, or it is another user's Agent |
409 | agent_in_use | The Agent is placed in projects (with force=true, it is removed from the placements and deleted) |
409 | agent_running | A sweep of this Agent is running |
409 | admin_stopped | An administrator has stopped this Agent |
POST/v1/agents/:agentId/copy
Copies a shared Agent as your own Agent. A newly created copy is private. No body is required (a body is not read even if sent).
The definition is copied as is. The playbook, skills, and input files it points to are adjusted so that the user making the copy can use them, as follows.
- Playbook: If it is not your own, it is duplicated as your own playbook, and the copy points to the duplicate. In a tenant where publishing approval is enabled, a playbook that is not shared is removed instead of duplicated, and for a shared playbook the approved content is duplicated
- Skills: Your own skills and skills that are shared and active are kept as they are (if the source Agent specifies a version, that version is used; otherwise, the owner's current version is used). When a version of a shared skill is specified, only a version that has been shared is kept as it is. Other skills have the version in use duplicated as your own skill, and the copy points to the duplicate. In a tenant where publishing approval is enabled, a skill that is not shared or is inactive (including one pinned to a version that has never been shared) is removed instead of duplicated
- Input files: They are not duplicated. Those that are not in your library are removed
- Playbooks and skills that cannot be found are removed
If the definition cannot be adjusted this way (for example, when it points to one of your own skills that is inactive), the playbook, skills, and input files are all removed before copying. For a registered Agent of the Marketplace edition, if you already have your own Agent for the same registered Agent, that Agent is returned instead of creating a new one.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
agentId | string | 必須 | ID of the Agent to copy (UUID) |
Request Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | — | A key to identify resends (8 to 128 characters of letters, digits, and _ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy \2-H "Authorization: Bearer <access_token>" \3-H "Idempotency-Key: copy-agent-20261118-0001"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy \ -H "Authorization: Bearer <access_token>" \ -H "Idempotency-Key: copy-agent-20261118-0001"
import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy",
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-agent-20261118-0001"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Idempotency-Key": "copy-agent-20261118-0001",
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/agents/17be0242-a5d0-4db7-92e5-f97a05abae2b/copy", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-agent-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the Agent created by the copy in the same form as the Get Agent response (without adminStop; check it with List or Get), with the following three fields added. For a registered Agent of the Marketplace edition, your existing Agent may be returned (in that case, projectCount in the response is 0; check the number of projects with the Get Agent API).
| Field | Type | Description |
|---|---|---|
duplicated | object | Numbers of items duplicated as your own (playbooks: number of playbooks, skills: number of skills) |
strippedInputFiles | string[] | When input files were removed (including when the definition could not be adjusted and everything was removed), contains one item: the name of the copied Agent. Empty if nothing was removed. These are not the names of the removed files |
strippedResources | string[] | In a tenant where publishing approval is enabled, when a playbook that is not shared, or a skill that is not shared or is inactive (including a pin to a version that has never been shared), was removed, contains one item: the name of the copied Agent. Empty if nothing was removed. These are not the names of the removed playbooks or skills |
If you resend with the same Idempotency-Key, 200 OK is returned with the first copy in the same form. In that case, duplicated is 0, and strippedInputFiles and strippedResources are empty (a resend duplicates nothing new). If the first copy has been deleted, 404 Not Found (agent_not_found) is returned; send the request with a new key.
Response Example
{
"agentId": "2c9d4e6f-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
"name": "Order data import",
"description": "Create order data from order emails",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"isShared": false,
"shareScope": "all",
"shareOrganizations": null,
"runtimeKind": "autonomous",
"marketplaceAgentId": null,
"spec": {
"goal": "Create an order data table from the order emails received.",
"guardrail": "Do not send anything to external services.",
"skills": [
{
"skillId": "cb62d540-5439-4748-99f0-961b8de91a78",
"name": "order-parser",
"versionId": null
}
],
"playbookId": "2f6a8c0e-4b1d-4a3c-9e5f-7d9b1a3c5e70",
"inputFiles": [
{
"type": "blob",
"filepath": "/path/to/orders-template.xlsx",
"filename": "orders-template.xlsx"
}
],
"agentLevel": "default",
"orgId": null,
"jobRole": null,
"agentConfig": null,
"exposureConsent": null
},
"projectCount": 0,
"copyCount": 0,
"createdAt": "2026-09-20T02:10:00.000Z",
"updatedAt": "2026-09-28T15:18:02.255Z",
"digest": "SBD5evHBJXCLMJy93n5V7KQJQn9o_NmbPmvgYSQFLSo",
"duplicated": {
"playbooks": 1,
"skills": 0
},
"strippedInputFiles": [],
"strippedResources": []
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | agentId is not a UUID |
400 | idempotency_key_invalid | The format of Idempotency-Key is invalid |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
403 | sso_required | The user does not sign in with SSO |
404 | agent_not_found | The Agent does not exist, it is another user's private Agent, or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
409 | already_owned | You tried to copy your own Agent |
409 | idempotency_conflict | A copy of a different Agent was sent with the same Idempotency-Key |
409 | admin_stopped | An administrator has stopped this Agent |
Skills
Reads, creates, edits, deletes, and copies skills. Use a skillId in the Chat skillIds parameter to load the skill into the agent, or in an Agent definition (spec.skills). For the common rules, see Common Rules for Agents, Playbooks, and Skills.
A skill consists of SKILL.md and accompanying files (documents, scripts, setting files, and so on). Each time the files change, a new version is created, and earlier versions are kept.
Use GET /v1/skills for skills you registered yourself, and GET /v1/skills/shared for publicly shared skills (including those you shared yourself). Shared skills can be specified in skillIds directly without copying them.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/skills | List your skills | chat:exec / assets:read |
| GET | /v1/skills/shared | List shared skills | chat:exec / assets:read |
| GET | /v1/skills/:skillId | Get a skill | assets:read |
| GET | /v1/skills/:skillId/versions | List the versions of a skill | assets:read |
| GET | /v1/skills/:skillId/files | List the files of a skill | assets:read |
| GET | /v1/skills/:skillId/files/content | Get one file of a skill | assets:read |
| GET | /v1/skills/:skillId/download | Get the files of a skill as a zip | assets:read |
| POST | /v1/skills | Create a skill | assets:write |
| PUT | /v1/skills/:skillId/files | Replace the files of a skill | assets:write |
| PATCH | /v1/skills/:skillId/files | Edit the documents of a skill | assets:write |
| PATCH | /v1/skills/:skillId | Change the settings of a skill | assets:write |
| DELETE | /v1/skills/:skillId | Delete a skill | assets:delete |
| POST | /v1/skills/:skillId/copy | Copy a skill as your own skill | assets:write |
GET/v1/skills
Lists the skills you registered, ordered by last update time (newest first). Cursor-based pagination is supported.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
active_only | boolean | true | Set to false to also include deactivated skills. A value other than "true" / "false" returns 400 |
limit | integer | 50 | Number of items per page (1-100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
skills | array | Array of skill objects |
skills[].skillId | string | Skill ID (specify this in the Chat skillIds parameter) |
skills[].ownerUserId | string | null | User ID of the owner |
skills[].name | string | Skill name |
skills[].description | string? | Skill description |
skills[].category | string? | Category |
skills[].tags | array | Array of tags (duplicates are returned once). An empty array when unset |
skills[].isShared | boolean | Whether you share the skill publicly |
skills[].isActive | boolean | Whether the skill is active |
skills[].shareRequestStatus | string | null | Status of the publishing request (see "Publishing Approval for Skills and Playbooks"). sharePendingVersionId, sharePendingListing, shareRequestNote, shareReviewNote, and shareRequestedAt are also included |
skills[].createdAt | string | Creation time (ISO 8601) |
skills[].updatedAt | string | Last update time (ISO 8601) |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"skills": [
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "devops",
"tags": ["ci"],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}
Pagination
While hasMore is true, pass the cursor from the response to the next request as-is.
# 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.
The cursor represents a position in the result set. Do not change active_only while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
Items may also be duplicated or skipped across pages if skills are added or removed while you are paging.
Error Responses
| Status | Description |
|---|---|
400 | limit is not an integer between 1 and 100 |
400 | cursor is invalid (not a value from a previous response) |
400 | active_only is not "true" / "false" |
403 | Has neither chat:exec nor assets:read |
403 | Called with a system integration token (code: "forbidden") |
GET/v1/skills/shared
Lists publicly shared skills (including skills you shared yourself), ordered by creation time (newest first). Cursor-based pagination is supported.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Number of items per page (1-100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared?limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared?limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/shared?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
Shared skills are always active, so the isShared / isActive fields are not included. The request status fields are not included either.
| Field | Type | Description |
|---|---|---|
skills | array | Array of skill objects |
skills[].skillId | string | Skill ID (specify this in the Chat skillIds parameter) |
skills[].ownerUserId | string | null | User ID of the owner |
skills[].name | string | Skill name |
skills[].description | string? | Skill description |
skills[].category | string? | Category |
skills[].tags | array | Array of tags (duplicates are returned once). An empty array when unset |
skills[].createdAt | string | Creation time (ISO 8601) |
skills[].updatedAt | string | Last update time (ISO 8601) |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"skills": [
{
"skillId": "9c8b7a6d-5e4f-4a3b-8c1d-2e3f4a5b6c7d",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "sql-review",
"description": "Review SQL statements",
"category": null,
"tags": [],
"createdAt": "2026-07-20T00:00:00.000Z",
"updatedAt": "2026-08-09T00:00:00.000Z"
}
],
"hasMore": false
}
Error Responses
| Status | Description |
|---|---|
400 | limit is not an integer between 1 and 100 |
400 | cursor is invalid (not a value from a previous response) |
403 | Has neither chat:exec nor assets:read |
403 | Called with a system integration token (code: "forbidden") |
GET/v1/skills/:skillId
Gets a skill. You can get your own skills and shared skills.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
The same fields as an item in the list of your skills, plus the following two. For a skill shared by another user, isShared, isActive, and the request status fields are not included, as in the shared list.
| Field | Type | Description |
|---|---|---|
currentVersionId | string | null | ID of the current version. null for a skill that was created before versions were recorded and whose files have not been changed since |
digest | string | The value to send as baseDigest when changing the skill settings. It is made from the shared setting, active setting, category, and tags, and does not change when the files change |
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generates release notes",
"category": "devops",
"tags": ["ci"],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's private skill |
GET/v1/skills/:skillId/versions
Lists the versions of a skill. Each time the files of a skill change, a new version is created, and earlier versions are kept. Up to 100 versions are returned, newest first. Pagination is not supported (hasMore is always false, and versions older than the latest 100 are not returned). If you know the ID of a version older than the latest 100, you can still get its file list and read its non-binary documents and its non-document text files of up to 200 KiB with the single-file API (to read all its files, copy the skill with that version).
For another user's shared skill, only the versions shared while it was shared are returned. Versions awaiting approval or sent back, and versions made while it was not shared, are not returned. For a skill whose sharing an administrator stopped, after it is shared again only the version at the time it was shared again and the versions shared after that are returned (versions from before the stop are not returned). Specifying a version that is not returned gives 400 Bad Request (version_not_found).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/versions", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
skillId | string | Skill ID |
currentVersionId | string | null | ID of the current version |
versions | array | Array of versions (newest first) |
versions[].versionId | string | null | Version ID |
versions[].versionNo | number | Version number (starting from 1) |
versions[].parentVersionId | string | null | ID of the version this version was based on |
versions[].source | string | How the version was created: "upload" (created or replaced by sending files), "edit" (documents were edited), "copy" (created by a copy), "baseline" (content from before versions were recorded), or "listing" (created to wait for approval of a category or tags change on a shared skill) |
versions[].contentDigest | string | null | A value made from the contents of the files of the version. Versions with the same contents have the same value |
versions[].createdAt | string | When the version was created (ISO 8601) |
versions[].isCurrent | boolean | Whether this is the current version |
hasMore | boolean | Always false |
For a skill that was created before versions were recorded and whose files have not been changed since, one item is returned with versionId and contentDigest set to null and source set to "baseline".
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versions": [
{
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versionNo": 2,
"parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"source": "edit",
"contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
"createdAt": "2026-08-05T09:00:00.000Z",
"isCurrent": true
},
{
"versionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"versionNo": 1,
"parentVersionId": null,
"source": "upload",
"contentDigest": "3cd01ce0220c4f7a9b1d3e5f70a2c4e6b8d0f1a3c5e7b9d1f3a5c7e9b0d2f4a6",
"createdAt": "2026-08-01T03:12:45.123Z",
"isCurrent": false
}
],
"hasMore": false
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's private skill |
GET/v1/skills/:skillId/files
Lists the files of a version of a skill. File contents are not returned (read them with the single-file API).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
version_id | string | Current version | ID of the version to read (UUID). The earlier name versionId is also accepted. If omitted and the owner reads a skill that has a version awaiting approval or returned for publishing, that version is read |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
skillId | string | Skill ID |
versionId | string | null | Version ID |
isCurrent | boolean | Whether this is the current version |
digest | string | The value to send as baseDigest when replacing the files of the skill or editing its documents (send the value from the file list read without version_id) |
editable | boolean | Whether the documents can be edited. true when it is your own skill and it contains no scripts or executables (.exe, .bin, .so, .dylib, .dll) |
files | array | Array of files (in path order) |
files[].path | string | Path within the skill (for example, scripts/run.py) |
files[].kind | string | Kind of the file (decided by the extension): "document" (.md, .json, .yaml, .yml), "script" (.py, .js, .mjs, .cjs, .ts, .sh, .bash, .zsh, .rb, .pl, .php, .go, .rs, .java, .ps1, .bat, .cmd), or "other" (anything else, such as setting files and images) |
files[].size | number | Size (bytes) |
files[].editable | boolean | Whether the file is in a form whose contents can be changed by editing documents (true for a document that is not binary) |
hasMore | boolean | Always false (all items are returned) |
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"isCurrent": true,
"digest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
"editable": true,
"files": [
{ "path": "SKILL.md", "kind": "document", "size": 1834, "editable": true },
{ "path": "templates/notes.md", "kind": "document", "size": 412, "editable": true }
],
"hasMore": false
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId or version_id is not a UUID, or version_id and versionId have different values |
400 | version_not_found | version_id is not a version of the skill |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's private skill |
GET/v1/skills/:skillId/files/content
Gets the contents of one file of a skill. The contents are always returned in full.
In an earlier version, documents (kind is "document" and the file is not binary; returned in full regardless of size) and text files of up to 200 KiB can be read. The same applies to the published version when the owner has a version awaiting approval or returned for publishing (if you omit the version, all the files of that version can be read). Binary files (including documents) and non-document files larger than 200 KiB in these versions return 400 (version_not_readable). To read all the files of an earlier version, copy the skill with versionId (POST /v1/skills/:skillId/copy), and then download the copied skill (GET /v1/skills/:skillId/download).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
path | string | — | Required. Path of the file (files[].path in the file list; for example, scripts/run.py) |
version_id | string | Current version | ID of the version to read (UUID). The earlier name versionId is also accepted. If omitted and the owner reads a skill that has a version awaiting approval or returned for publishing, that version is read |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content",
headers={"Authorization": f"Bearer {token}"},
params={"path": "SKILL.md"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content" + "?path=SKILL.md",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files/content?path=SKILL.md", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
skillId | string | Skill ID |
versionId | string | null | Version ID |
path | string | Path of the file |
kind | string | Kind of the file (same as files[].kind in the file list) |
size | number | Size (bytes) |
encoding | string | How the contents are represented: "utf-8" for a text file, or "base64" for a binary file (one whose contents include NUL) |
content | string | Contents of the file (in full) |
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"path": "SKILL.md",
"kind": "document",
"size": 88,
"encoding": "utf-8",
"content": "---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId or version_id is not a UUID, version_id and versionId have different values, or path is missing |
400 | file_not_found | The file at path is not in the version |
400 | version_not_found | version_id is not a version of the skill |
400 | version_not_readable | A binary file (including a document) or a non-document file larger than 200 KiB was specified in an earlier version (or, when the owner has a version awaiting approval or returned for publishing, in the published version) |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's private skill |
GET/v1/skills/:skillId/download
Gets all the files (including setting files and images) of the current version of a skill (when the owner downloads a skill that has a version awaiting approval or returned for publishing, that version) as a zip. You cannot specify a version.
- The
Content-Typeof the response isapplication/zip. The file name (Content-Disposition) is based on the name of the skill (with the.zipextension). - The zip has no top-level folder. You can send it as is to create a skill (
POST /v1/skills) or to replace the files of a skill (PUT /v1/skills/:skillId/files).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's private skill |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/download", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)POST/v1/skills
Creates a skill. Send the request as multipart/form-data. The name and description are read from name and description in the YAML at the top of SKILL.md (the part enclosed in ---).
Request Body (multipart/form-data)
| Field | Type | Required | Description |
|---|---|---|---|
files | file | Yes | Files of the skill. Send one zip, or a set of files that includes SKILL.md. For a set of files, send one file per field, and set the file name to the path within the skill (for example, scripts/run.py). If you send only one file with the .md extension, it is saved as SKILL.md |
category | string | — | Category (up to 40 characters, not counting leading and trailing whitespace) |
tags | string | — | Tags. Send one tag per field and repeat the field (up to 10 tags of 1 to 24 characters, not counting leading and trailing whitespace or a leading #). Tags are saved in lowercase without a leading #. Tags that become the same this way cannot be sent |
isShared | string | — | Whether to share it ("true" or "false"). Private if omitted |
isActive | string | — | Whether it is active ("true" or "false"). Active if omitted. A shared skill must be active |
shareRequestNote | string | — | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |
Rules for the files of a skill:
SKILL.mdis required at the root. The YAML at the top ofSKILL.mdmust havename(up to 100 characters).descriptionis optional (in the description shown in lists and elsewhere, the part over 1024 characters is cut off;SKILL.mditself is kept as is).- If the contents of a zip are all in one folder, the folder is removed when saving. Files created by operating systems (
__MACOSX/, files starting with._,.DS_Store,Thumbs.db,desktop.ini) are not saved. - 1 to 50 files, up to 2 MiB per file, and up to 5 MiB in total after extraction.
- Keep the total size of the files you send (including the size after a set of files is packed) under 6 MiB.
- The contents go through a safety check.
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills \2-H "Authorization: Bearer <access_token>" \3-F "files=@SKILL.md" \4-F "category=devops" \5-F "tags=ci"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills \ -H "Authorization: Bearer <access_token>" \ -F "files=@SKILL.md" \ -F "category=devops" \ -F "tags=ci"
import requests
with open("SKILL.md", "rb") as f:
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills",
headers={"Authorization": f"Bearer {token}"},
files={"files": f},
data={"category": "devops", "tags": "ci"},
)
print(response.json())const formData = new FormData();
formData.append("files", file); // File object
formData.append("category", "devops");
formData.append("tags", "ci");
const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills", {
method: "POST",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});
const data = await response.json();
console.log(data);file, _ := os.Open("SKILL.md")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "SKILL.md")
io.Copy(part, file)
writer.WriteField("category", "devops")
writer.WriteField("tags", "ci")
writer.Close()
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the created skill in the same form as the response for getting your own skill.
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | files is missing, two files with the same path were sent, a file was sent in a field other than files, there are too many or too long form fields, or category, tags, isShared, or isActive is invalid |
400 | file_count | No files (for example, an empty zip) or more than 50 files |
400 | file_too_large | A file exceeds 2 MiB |
400 | total_too_large | The total after extraction exceeds 5 MiB |
400 | zip_invalid | The zip cannot be extracted |
400 | bad_path | A file path is invalid (for example, it contains ..) |
400 | skill_md_missing | SKILL.md is not at the root |
400 | frontmatter_missing | SKILL.md does not start with YAML (the part enclosed in ---) |
400 | name_missing | The YAML in SKILL.md has no name |
400 | name_too_long | The name in SKILL.md exceeds 100 characters |
400 | shared_requires_active | Tried to share the skill while it is inactive |
400 | guardrail_blocked | The contents were blocked by the safety check |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
413 | body_too_large | The total size of the files sent exceeds the limit |
415 | unsupported_media_type | The Content-Type is not multipart/form-data |
502 | blob_write_failed | The files could not be saved (resend the request) |
503 | guardrail_unavailable | The safety check is not available (resend the request later) |
curl -X POST "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills" \
-H "Authorization: Bearer <access_token>" \
-F "files=@SKILL.md;filename=SKILL.md" \
-F "files=@scripts/run.py;filename=scripts/run.py" \
-F "category=devops" \
-F "tags=ci" \
-F "tags=release"
PUT/v1/skills/:skillId/files
Replaces all the files of one of your skills with the files you send. A new version is created, and earlier versions are kept. Files you do not send are not included in the new version. Send the request as multipart/form-data.
- The name and description are read again from the new
SKILL.md. - Agents and schedules that use this skill without fixing a version start using the new version (those that fix a version do not change). For a shared skill in a tenant where publishing approval is enabled, the previous version stays in use until the new version is approved.
- If you resend the request,
409 Conflict(stale_base) is returned because the first request changed the version. Get the file list again and check whether the files were changed.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Request Body (multipart/form-data)
| Field | Type | Required | Description |
|---|---|---|---|
baseDigest | string | Yes | The digest from the file list read without version_id |
files | file | Yes | Files of the skill. How to send them and the rules are the same as when creating a skill |
shareRequestNote | string | — | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |
The category, tags, shared setting, and active setting are not accepted (they are not read even if sent). Change them by changing the settings of the skill (PATCH /v1/skills/:skillId).
In a tenant where publishing approval is enabled, changing the content of a skill awaiting approval keeps it awaiting approval, with the changed content. If you change the content of a skill awaiting approval after the administrator stops requiring approval, the change shares it. This is the same as changing it on the screen (see Publishing Approval).
baseDigest is checked before checking whether you may change the skill. For this reason, for a skill shared by another user, 409 Conflict is returned if baseDigest does not match, and 404 Not Found is returned if it matches.
Request Example
1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \2-H "Authorization: Bearer <access_token>" \3-F "files=@SKILL.md" \4-F "baseDigest=WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \ -H "Authorization: Bearer <access_token>" \ -F "files=@SKILL.md" \ -F "baseDigest=WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"
import requests
with open("SKILL.md", "rb") as f:
response = requests.put(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
headers={"Authorization": f"Bearer {token}"},
files={"files": f},
data={"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0"},
)
print(response.json())const formData = new FormData();
formData.append("files", file); // File object
formData.append("baseDigest", "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0");
const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", {
method: "PUT",
headers: { "Authorization": "Bearer " + accessToken },
body: formData,
});
const data = await response.json();
console.log(data);file, _ := os.Open("SKILL.md")
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("files", "SKILL.md")
io.Copy(part, file)
writer.WriteField("baseDigest", "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0")
writer.Close()
req, _ := http.NewRequest("PUT", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
Returns the skill after the replacement (with a new currentVersionId) in the same form as the response for getting your own skill. For a shared skill in a tenant where publishing approval is enabled, currentVersionId does not change and the ID of the new version is in sharePendingVersionId. Get the digest of the new version from the file list.
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-06T10:00:00.000Z",
"currentVersionId": "8c2e4a6b-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID, baseDigest is missing, empty, or not a string, files is missing, two files with the same path were sent, or a file was sent in a field other than files |
400 | file_count | No files (for example, an empty zip) or more than 50 files |
400 | file_too_large | A file exceeds 2 MiB |
400 | total_too_large | The total after extraction exceeds 5 MiB |
400 | zip_invalid | The zip cannot be extracted |
400 | bad_path | A file path is invalid (for example, it contains ..) |
400 | skill_md_missing | SKILL.md is not at the root |
400 | frontmatter_missing | SKILL.md does not start with YAML (the part enclosed in ---) |
400 | name_missing | The YAML in SKILL.md has no name |
400 | name_too_long | The name in SKILL.md exceeds 100 characters |
400 | guardrail_blocked | The contents were blocked by the safety check |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's skill |
409 | stale_base | The files of the skill have changed since you got the file list |
413 | body_too_large | The total size of the files sent exceeds the limit |
415 | unsupported_media_type | The Content-Type is not multipart/form-data |
502 | blob_write_failed | The files could not be saved |
503 | guardrail_unavailable | The safety check is not available (resend the request later) |
PATCH/v1/skills/:skillId/files
Edits the documents (.md, .json, .yaml, .yml) of one of your skills. A new version is created in which only the documents you send are changed; files you do not send are carried over from the current version (or, if there is a version awaiting approval or returned for publishing, from that version). Earlier versions are kept.
- You can add, rewrite, and delete documents. Files that are not documents cannot be changed. A skill that contains scripts or executables cannot be edited (fix it by replacing the files with
PUT /v1/skills/:skillId/files). SKILL.mdcannot be deleted. WhenSKILL.mdis rewritten, the name and description are read again.- The syntax of JSON and YAML documents is checked. After the edit, the skill must still have up to 50 files, up to 2 MiB per file, and up to 5 MiB in total. Edited documents go through a safety check.
- Agents and schedules that use this skill without fixing a version start using the new version (those that fix a version do not change). For a shared skill in a tenant where publishing approval is enabled, the previous version stays in use until the new version is approved.
- A note for the publishing request (
shareRequestNote) cannot be sent (sending it returns400 Bad Request(invalid_parameter)). To attach a note, send it with Replace Skill Files (PUT /v1/skills/:skillId/files). In a tenant where publishing approval is enabled, fixing the version awaiting approval of a shared skill with this API keeps the note for the request.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Request Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | — | A key to identify resends (8 to 128 characters of letters, digits, and _ . : -). If you resend with the same key, the version created by the first request is returned without creating a new version |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
baseDigest | string | Yes | The digest from the file list read without version_id |
changes | array | Yes | Documents to change (1 to 50; each path only once) |
changes[].path | string | Yes | Path of the document (for example, SKILL.md or templates/notes.md). A path that does not exist adds a document |
changes[].content | string | — | New contents of the document (in full). Omit it when deleting |
changes[].deleted | boolean | — | true deletes the document (true or false; other values cannot be sent) |
{
"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
"changes": [
{ "path": "SKILL.md", "content": "---\nname: release-notes\ndescription: Generates release notes\n---\n\n# Steps\n..." },
{ "path": "templates/old.md", "deleted": true }
]
}
Request Example
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \2-H "Authorization: Bearer <access_token>" \3-H "Idempotency-Key: edit-skill-20261118-0001" \4-H "Content-Type: application/json" \5-d '{6 "baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",7 "changes": [8 {9 "path": "SKILL.md",10 "content": "---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n"11 },12 {13 "path": "templates/old.md",14 "deleted": true15 }16 ]17}'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: edit-skill-20261118-0001" \
-H "Content-Type: application/json" \
-d '{
"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0",
"changes": [
{
"path": "SKILL.md",
"content": "---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n"
},
{
"path": "templates/old.md",
"deleted": true
}
]
}'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "edit-skill-20261118-0001"},
json={'baseDigest': 'WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0', 'changes': [{'path': 'SKILL.md', 'content': '---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n'}, {'path': 'templates/old.md', 'deleted': True}]},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Idempotency-Key": "edit-skill-20261118-0001",
"Content-Type": "application/json",
},
body: JSON.stringify({"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0", "changes": [{"path": "SKILL.md", "content": "---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n"}, {"path": "templates/old.md", "deleted": true}]}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"baseDigest": "WyI1YjFkN2UyYS04YzRmLTRlOWItYTNkNi0yZjdjOWUxYjRhODAiLCI3OGE0ZWE1YWFkZTNiMWMwZDlmNmU3YTJiNGM4ZDFlM2Y1YTdiOWMwZDJlNGY2YThiMGMxZDNlNWY3YTliMmM0Il0", "changes": [{"path": "SKILL.md", "content": "---\nname: release-notes\ndescription: Generate release notes\n---\n\n# Steps\n"}, {"path": "templates/old.md", "deleted": true}]}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/files", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "edit-skill-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
| Field | Type | Description |
|---|---|---|
skill | object | The skill after the edit (same form as the response for getting your own skill, except that sharePendingListing is not included; read it by getting the skill) |
version | object | The created version (same form as an item of versions[] in the version list) |
If you resend with the same Idempotency-Key, 200 OK is returned with the version created by the first request (version) and the current skill (skill). Sending a different edit with the same key returns 409 Conflict (command_conflict). Resending before the first request finishes may return 409 Conflict (stale_base); resend with the same key after it finishes.
Response Example
{
"skill": {
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
},
"version": {
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"versionNo": 2,
"parentVersionId": "e2c4a6b8-1d3f-4a5c-9e7b-0f2d4c6a8e1b",
"source": "edit",
"contentDigest": "78a4ea5aade3b1c0d9f6e7a2b4c8d1e3f5a7b9c0d2e4f6a8b0c1d3e5f7a9b2c4",
"createdAt": "2026-08-05T09:00:00.000Z",
"isCurrent": true
}
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID, baseDigest is missing, empty, or not a string, changes[].deleted is not true or false, or shareRequestNote was sent |
400 | idempotency_key_invalid | The format of Idempotency-Key is invalid |
400 | invalid_body | The body is malformed JSON or not a JSON object |
400 | no_changes | changes is missing or empty, or has more than 50 items |
400 | bad_change | An item of changes has the wrong form (path is missing, content is not a string, and so on), or the same path was specified twice |
400 | bad_path | path is invalid (for example, it contains ..) |
400 | not_editable | A file that is not a document was specified |
400 | code_skill_not_editable | The skill contains scripts or executables |
400 | skill_md_required | Tried to delete SKILL.md |
400 | file_too_large | A file exceeds 2 MiB |
400 | invalid_syntax | A JSON or YAML document has a syntax error |
400 | skill_too_large | After the edit, the skill exceeds 50 files or 5 MiB in total |
400 | frontmatter_missing | SKILL.md does not start with YAML (the part enclosed in ---) |
400 | name_missing | The YAML in SKILL.md has no name |
400 | name_too_long | The name in SKILL.md exceeds 100 characters |
400 | guardrail_blocked | The contents were blocked by the safety check |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's skill |
409 | stale_base | The files of the skill have changed since you got the file list (including an unreadable baseDigest) |
409 | command_conflict | A different edit was sent with the same Idempotency-Key |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
502 | blob_write_failed | The files could not be saved |
503 | guardrail_unavailable | The safety check is not available (resend the request later) |
PATCH/v1/skills/:skillId
Changes the settings of one of your skills (shared setting, active setting, category, and tags). Only the fields you send are changed. The name and description are read from SKILL.md, so they cannot be changed here.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
baseDigest | string | Yes | The digest from the Get Skill response |
isShared | boolean | — | Whether to share it. In a tenant where publishing approval is enabled, true makes it wait for approval, and sending false to an item awaiting approval withdraws the request |
isActive | boolean | — | Whether it is active |
category | string | null | — | Category (up to 40 characters, not counting leading and trailing whitespace). Send null or an empty string to clear it. For a shared skill in a tenant where publishing approval is enabled, the change waits for approval unless isShared false is sent in the same call (see "Publishing Approval for Skills and Playbooks") |
tags | array | — | Tags (up to 10 strings of 1 to 24 characters, not counting leading and trailing whitespace or a leading #). Send [] to clear them. Tags are saved in lowercase without a leading #. Tags that become the same this way cannot be sent. For a shared skill in a tenant where publishing approval is enabled, the change waits for approval unless isShared false is sent in the same call (see "Publishing Approval for Skills and Playbooks") |
shareRequestNote | string | null | — | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |
Send at least one field besides baseDigest (shareRequestNote does not count). You can also send a note for the publishing request (shareRequestNote; see Publishing Approval). A change that would leave the skill shared but inactive returns 400 (shared_requires_active).
baseDigest is checked before checking whether you may change the skill. For this reason, for a skill shared by another user, 409 Conflict is returned if baseDigest does not match, and 404 Not Found is returned if it matches.
Request Example
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro",6 "category": "release"7}'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro",
"category": "release"
}'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
headers={"Authorization": f"Bearer {token}"},
json={'baseDigest': '8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro', 'category': 'release'},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro", "category": "release"}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"baseDigest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro", "category": "release"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
Returns the changed skill (with its current digest) in the same form as the response for getting your own skill. When you change the category or tags of a shared skill in a tenant where publishing approval is enabled (without sending isShared: false in the same call), category and tags keep the previous values, and the new values are in sharePendingListing (shareRequestStatus is "pending"). Changing only the category or tags does not change the digest.
Response Example
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "release",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"currentVersionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80",
"digest": "ZEs4wUG1R0Xfjmy6jVkkMLsikpWmXBZKAziwGO0gj9k"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, or a field has the wrong type, length, or number of items |
400 | shared_requires_active | After the change, the skill would be shared but inactive |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's skill |
409 | stale_base | The settings of the skill have changed since you got it |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
DELETE/v1/skills/:skillId
Deletes one of your skills together with the files of all its versions. A system administrator can also delete skills shared by other users.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | Skill ID (UUID) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
force | string | "false" | Set to "true" to delete the skill even if schedules or Agents use it. A value other than "true" / "false" returns 400 |
- When the skill is in use: If schedules use this skill or Agents have it in their definitions,
409 Conflict(skill_referenced; the numbers of schedules and Agents are inerror.message) is returned. The schedules of all users are counted, whether active or inactive. Agents are counted regardless of their owners. Project jobs (sweeps of Agents placed in projects, and project executions that have not started yet) are not counted as schedules. - With
force=true: The skill is removed from the schedules that use it (including other users' schedules; the schedules themselves are kept) and from the definitions of all users' Agents, and then deleted. The sweeps of those Agents keep running with the definitions after the removal.
Request Example
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false" \2-H "Authorization: Bearer <access_token>"curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
headers={"Authorization": f"Bearer {token}"},
params={"force": "false"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c" + "?force=false",
{
method: "DELETE",
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
{
"skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
"deleted": true
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId is not a UUID, or force is not "true" / "false" |
403 | insufficient_scope | The assets:delete scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, or it is another user's skill that you cannot delete |
409 | skill_referenced | Schedules or Agents use the skill (it can be deleted with force=true) |
POST/v1/skills/:skillId/copy
Copies one of your skills or a shared skill as a new skill of your own. All the files of the specified version (the current version if omitted; when the owner copies a skill that has a version awaiting approval or returned for publishing, that version) are copied, and the copy is created as private and active. The name, description, category, and tags are copied from the current values of the source. The versions of the copied skill start from 1.
The body is optional. To specify a version, send it as JSON.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
skillId | string | 必須 | ID of the skill to copy (UUID) |
Request Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | — | A key to identify resends (8 to 128 characters of letters, digits, and _ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
versionId | string | — | ID of the version to copy (UUID). The current version if omitted (when the owner copies a skill that has a version awaiting approval or returned for publishing, that version) |
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy \2-H "Authorization: Bearer <access_token>" \3-H "Idempotency-Key: copy-skill-20261118-0001" \4-H "Content-Type: application/json" \5-d '{6 "versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"7}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: copy-skill-20261118-0001" \
-H "Content-Type: application/json" \
-d '{
"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy",
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-skill-20261118-0001"},
json={'versionId': '5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80'},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Idempotency-Key": "copy-skill-20261118-0001",
"Content-Type": "application/json",
},
body: JSON.stringify({"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"versionId": "5b1d7e2a-8c4f-4e9b-a3d6-2f7c9e1b4a80"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/skills/3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c/copy", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-skill-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the skill created by the copy in the same form as the response for getting your own skill.
If you resend with the same Idempotency-Key, 200 OK is returned with the first copy (its current contents) in the same form. If you omit versionId in the resend, the first copy is returned regardless of which version was copied the first time. If the first copy has been deleted, 404 Not Found (skill_not_found) is returned; send the request with a new key.
Response Example
{
"skillId": "9e1f3a5b-7c2d-4e6f-8a0b-1c3d5e7f9a2b",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "release-notes",
"description": "Generate release notes",
"category": "devops",
"tags": [
"ci"
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"sharePendingVersionId": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"sharePendingListing": null,
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"currentVersionId": "d7e9f1a3-5b2c-4d6e-8f0a-2c4e6a8b0d1f",
"digest": "8IaqLeFZ_E0H1mO92jido8Qk7Sn-rcwYYr71jvwS_Ro"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | skillId or versionId is not a UUID |
400 | idempotency_key_invalid | The format of Idempotency-Key is invalid |
400 | version_not_found | versionId is not a version of the skill |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | skill_not_found | The skill does not exist, it is another user's private skill, or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
409 | idempotency_conflict | A copy of a different skill, or a copy with a versionId different from the first request, was sent with the same Idempotency-Key |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
502 | blob_write_failed | The files could not be saved |
Playbooks
Reads, creates, edits, deletes, and copies playbooks. Use a playbookId in the Chat playbookId parameter to run the agent with a predefined procedure, or in an Agent definition (spec.playbookId). For the common rules, see Common Rules for Agents, Playbooks, and Skills.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/playbooks | List your playbooks | chat:exec / assets:read |
| GET | /v1/playbooks/shared | List shared playbooks | chat:exec / assets:read |
| GET | /v1/playbooks/:playbookId | Get a playbook | assets:read |
| POST | /v1/playbooks | Create a playbook | assets:write |
| PATCH | /v1/playbooks/:playbookId | Edit a playbook | assets:write |
| DELETE | /v1/playbooks/:playbookId | Delete a playbook | assets:delete |
| POST | /v1/playbooks/:playbookId/copy | Copy a shared playbook as your own playbook | assets:write |
GET/v1/playbooks
Lists playbooks, ordered by usage count (then by creation time, newest first). Cursor-based pagination is supported.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
active_only | boolean | true | Set to false to also include deactivated playbooks. A value other than "true" / "false" returns 400 |
limit | integer | 50 | Number of items per page (1-100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
playbooks | array | Array of playbook objects |
playbooks[].playbookId | string | Playbook ID (specify this in the Chat playbookId parameter) |
playbooks[].ownerUserId | string | User ID of the owner |
playbooks[].name | string | Playbook name |
playbooks[].description | string? | Description |
playbooks[].category | string? | Category |
playbooks[].tags | array | Array of tags (returned with leading and trailing whitespace removed, empty tags removed, and duplicates returned once) |
playbooks[].steps | array | Array of steps |
playbooks[].steps[].title | string | Step title |
playbooks[].steps[].description | string? | Step description |
playbooks[].steps[].guidance | array? | Array of supplementary instructions |
playbooks[].steps[].success | string? | Completion criteria |
playbooks[].sourceConversationId | string? | ID of the conversation the playbook was created from |
playbooks[].isShared | boolean | Whether the playbook is shared |
playbooks[].isActive | boolean | Whether the playbook is active |
playbooks[].shareRequestStatus | string | null | Status of the publishing request (see "Publishing Approval for Skills and Playbooks"). shareRequestNote, shareReviewNote, and shareRequestedAt are also included |
playbooks[].usageCount | number | Number of times used |
playbooks[].copyCount | number | Number of times copied |
playbooks[].createdAt | string | Creation time (ISO 8601) |
playbooks[].updatedAt | string | Last update time (ISO 8601) |
hasMore | boolean | Whether a next page exists |
cursor | string | Cursor for the next page. Included only when hasMore is true |
Response Example
{
"playbooks": [
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"name": "Weekly report",
"description": "Generate a weekly report from sales data",
"category": "Reporting",
"tags": ["sales", "weekly"],
"steps": [
{
"title": "Fetch data",
"description": "Fetch sales data for the target period",
"guidance": ["From Monday to Sunday of the previous week"],
"success": "At least one record was fetched"
}
],
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}
Pagination
While hasMore is true, pass the cursor from the response to the next request as-is.
# 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.
The cursor represents a position in the result set. Do not change active_only while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
Items may also be duplicated or skipped across pages if playbooks are added or removed while you are paging.
Error Responses
| Status | Description |
|---|---|
400 | limit is not an integer between 1 and 100 |
400 | cursor is invalid (not a value from a previous response) |
400 | active_only is not "true" / "false" |
403 | Has neither chat:exec nor assets:read |
403 | Called with a system integration token (code: "forbidden") |
GET/v1/playbooks/shared
Lists shared playbooks. The list also includes playbooks you shared and playbooks deactivated by the users who shared them. Ordered by the number of copies (then by creation time, newest first). Cursor-based pagination is supported.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Number of items per page (1-100) |
cursor | string | — | Cursor for the next page (the cursor value from the previous response) |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared?limit=20" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared?limit=20" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared",
headers={"Authorization": f"Bearer {token}"},
params={"limit": "20"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared" + "?limit=20",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/shared?limit=20", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
Same form as the list of your playbooks, except that each item does not include isShared, isActive, or the request status fields.
Response Example
{
"playbooks": [
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Weekly report creation",
"description": "Generate a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
],
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z"
}
],
"hasMore": false
}
Error Responses
| Status | Description |
|---|---|
400 | limit is not an integer between 1 and 100 |
400 | cursor is invalid (not a value from a previous response) |
403 | Has neither chat:exec nor assets:read |
403 | Called with a system integration token (code: "forbidden") |
GET/v1/playbooks/:playbookId
Gets a playbook. You can get your own playbooks and shared playbooks.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
playbookId | string | 必須 | Playbook ID (UUID) |
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
headers={"Authorization": f"Bearer {token}"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
{
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
The same fields as an item in the playbook list, plus digest. For a playbook shared by another user, isShared, isActive, and the request status fields are not included, as in the shared list.
| Field | Type | Description |
|---|---|---|
digest | string | The value to send as baseDigest when editing the playbook. It is made from the name, description, category, tags, steps, shared setting, and active setting, and does not change with the usage count, the copy count, or timestamps |
updatedAt is updated not only when the content is changed but also each time the playbook is used.
Response Example
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Weekly report creation",
"description": "Generate a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | playbookId is not a UUID |
403 | insufficient_scope | The assets:read scope is missing |
403 | forbidden | Called with a system integration token |
404 | playbook_not_found | The playbook does not exist, or it is another user's private playbook |
POST/v1/playbooks
Creates a playbook.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name (up to 100 characters; cannot be only whitespace) |
description | string | null | — | Description (up to 500 characters) |
category | string | null | — | Category (up to 50 characters) |
tags | array | — | Tags (up to 10 strings of up to 30 characters each. Empty or whitespace-only tags, and tags that are the same after removing leading and trailing whitespace, cannot be sent. Case is distinguished) |
steps | array | Yes | Steps (1 to 20) |
steps[].title | string | Yes | Step title (up to 100 characters; cannot be only whitespace) |
steps[].description | string | — | Step description (up to 1000 characters) |
steps[].guidance | array | — | Supplementary instructions (up to 10 strings of up to 500 characters each; empty or whitespace-only strings cannot be sent) |
steps[].success | string | — | Completion criteria (up to 500 characters) |
isShared | boolean | — | Whether to share it. Private if omitted |
isActive | boolean | — | Whether it is active. Active if omitted |
shareRequestNote | string | null | — | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |
- A step has four fields:
title,description,guidance, andsuccess(other fields are not saved).nullcannot 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 asnull.
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "name": "Weekly report creation",6 "description": "Generate a weekly report from sales data",7 "category": "Reports",8 "tags": [9 "sales",10 "weekly"11 ],12 "steps": [13 {14 "title": "Data retrieval",15 "description": "Retrieve sales data for the target period",16 "guidance": [17 "From Monday to Sunday of last week"18 ],19 "success": "At least one record of data has been retrieved"20 }21 ]22}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Weekly report creation",
"description": "Generate a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
]
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
headers={"Authorization": f"Bearer {token}"},
json={'name': 'Weekly report creation', 'description': 'Generate a weekly report from sales data', 'category': 'Reports', 'tags': ['sales', 'weekly'], 'steps': [{'title': 'Data retrieval', 'description': 'Retrieve sales data for the target period', 'guidance': ['From Monday to Sunday of last week'], 'success': 'At least one record of data has been retrieved'}]},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"name": "Weekly report creation", "description": "Generate a weekly report from sales data", "category": "Reports", "tags": ["sales", "weekly"], "steps": [{"title": "Data retrieval", "description": "Retrieve sales data for the target period", "guidance": ["From Monday to Sunday of last week"], "success": "At least one record of data has been retrieved"}]}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"name": "Weekly report creation", "description": "Generate a weekly report from sales data", "category": "Reports", "tags": ["sales", "weekly"], "steps": [{"title": "Data retrieval", "description": "Retrieve sales data for the target period", "guidance": ["From Monday to Sunday of last week"], "success": "At least one record of data has been retrieved"}]}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the created playbook in the same form as the response for getting your own playbook.
Response Example
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": null,
"name": "Weekly report creation",
"description": "Generate a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 0,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | name or steps is missing, or a field has the wrong type, length, or number of items (error.param names the field; a field in a step is shown like steps[2].title) |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
PATCH/v1/playbooks/:playbookId
Edits one of your playbooks. Only the fields you send are changed. When you send the steps (steps), all steps are replaced (express rewriting, removing, and reordering with this array).
When you change any of the name, description, category, tags, or steps, the previous content is kept as a version, and you can restore it from “Version history” in the web app. Changing only the sharing or enabled setting does not keep a version.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
playbookId | string | 必須 | Playbook ID (UUID) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
baseDigest | string | Yes | The digest from the Get Playbook response |
name | string | — | Name (up to 100 characters; cannot be only whitespace or null) |
description | string | null | — | Description (up to 500 characters). Send null or an empty string to clear it |
category | string | null | — | Category (up to 50 characters). Send null or an empty string to clear it |
tags | array | — | Tags (up to 10 strings of up to 30 characters each; the tags that cannot be sent are the same as when creating). Send [] to clear them |
steps | array | — | All the steps (1 to 20). The fields are the same as when creating a playbook |
isShared | boolean | — | Whether to share it. In a tenant where publishing approval is enabled, true makes it wait for approval, and sending false to an item awaiting approval withdraws the request |
isActive | boolean | — | Whether it is active |
shareRequestNote | string | null | — | Note for the publishing request (up to 2000 characters, not counting leading and trailing whitespace; see "Publishing Approval for Skills and Playbooks") |
Send at least one field besides baseDigest (shareRequestNote does not count). null cannot be sent for name, tags, steps, isShared, or isActive. Values are saved in the same way as when creating a playbook (leading and trailing whitespace), and the tags and supplementary instructions that cannot be sent are also the same.
If the first request changed the content, resending it returns 409 Conflict (stale_base) because the digest has changed. Get the playbook again and check whether it was changed.
In a tenant where publishing approval is enabled, changing the content (name, description, category, tags, or steps) of a playbook awaiting approval keeps it awaiting approval, with the changed content. If you change the content of a playbook awaiting approval after the administrator stops requiring approval, the change shares it. This is the same as changing it on the screen (see Publishing Approval).
In a tenant where publishing approval is enabled, changing the content of a shared playbook keeps it shared and makes a request (isShared in the response is true, and shareRequestStatus is "pending"). Until it is approved, other users see the approved content (see Publishing Approval).
Request Example
1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \2-H "Authorization: Bearer <access_token>" \3-H "Content-Type: application/json" \4-d '{5 "baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E",6 "description": "Create a weekly report from sales data"7}'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E",
"description": "Create a weekly report from sales data"
}'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
headers={"Authorization": f"Bearer {token}"},
json={'baseDigest': 'zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E', 'description': 'Create a weekly report from sales data'},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E", "description": "Create a weekly report from sales data"}),
}
);
const data = await response.json();
console.log(data);payload := []byte(`{"baseDigest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E", "description": "Create a weekly report from sales data"}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
Returns the edited playbook (with its current digest) in the same form as the response for getting your own playbook.
Response Example
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Weekly report creation",
"description": "Create a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 12,
"copyCount": 0,
"createdAt": "2026-08-01T03:12:45.123Z",
"updatedAt": "2026-08-05T09:00:00.000Z",
"digest": "DYEcDfkGIG6oOpm-WEd7l1UhFjZzruLKxM9yEYu9BTA"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | playbookId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, a field has the wrong type, length, or number of items, or null was sent for a field that does not accept it |
400 | invalid_body | The body is malformed JSON or not a JSON object |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | playbook_not_found | The playbook does not exist, or it is another user's playbook |
409 | stale_base | The playbook has changed since you got it |
413 | body_too_large | The body exceeds 3 MiB |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
DELETE/v1/playbooks/:playbookId
Deletes one of your playbooks. A system administrator can also delete playbooks shared by other users.
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
playbookId | string | 必須 | Playbook ID (UUID) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
force | string | "false" | Set to "true" to delete the playbook even if schedules or Agents use it. A value other than "true" / "false" returns 400 |
- When the playbook is in use: If active schedules use this playbook or Agents have it in their definitions,
409 Conflict(has_active_references; the numbers of active schedules and Agents are inerror.message) is returned. Agents are counted regardless of their owners. Project jobs (sweeps of Agents placed in projects, and project executions that have not started yet) are not counted as schedules. - With
force=true: The playbook is removed from the definitions of all users' Agents and deleted. The sweeps of those Agents keep running with the definitions after the removal. If active schedules use the playbook, the schedules that use it, including inactive ones, are deleted.- Only your own schedules are counted and deleted (also when a system administrator deletes their own playbook). Other users' schedules are neither counted nor deleted (they keep pointing to the deleted playbook). When a system administrator deletes a playbook shared by another user, the schedules of all users are counted and deleted.
- If only inactive schedules use the playbook,
409 Conflictis not returned unless Agents also use it. In either case, inactive schedules are not deleted even withforce=true, and they keep pointing to the deleted playbook. - Deleted schedules do not run after that (executions that have already started are not stopped).
Request Example
1curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false" \2-H "Authorization: Bearer <access_token>"curl -X DELETE "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.delete(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7",
headers={"Authorization": f"Bearer {token}"},
params={"force": "false"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7" + "?force=false",
{
method: "DELETE",
headers: {
"Authorization": "Bearer " + accessToken,
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("DELETE", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7?force=false", nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (200 OK)
{
"playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"deleted": true
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | playbookId is not a UUID, or force is not "true" / "false" |
403 | insufficient_scope | The assets:delete scope is missing |
403 | forbidden | Called with a system integration token |
404 | playbook_not_found | The playbook does not exist, or it is another user's playbook that you cannot delete |
409 | has_active_references | Active schedules or Agents use the playbook (it can be deleted with force=true) |
409 | admin_stopped | When deleting with force=true, active schedules use this playbook and an administrator has stopped one of them |
POST/v1/playbooks/:playbookId/copy
Copies a shared playbook as your own playbook. The name, description, category, tags, and steps are copied, and the copy is created as private and active. The number of copies of the source (copyCount) increases by 1. No body is required (a body is not read even if sent).
Path Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
playbookId | string | 必須 | ID of the playbook to copy (UUID) |
Request Headers
| Header | Required | Description |
|---|---|---|
Idempotency-Key | — | A key to identify resends (8 to 128 characters of letters, digits, and _ . : -). If you resend with the same key, the copy created by the first request is returned without creating a new one |
Request Example
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy \2-H "Authorization: Bearer <access_token>" \3-H "Idempotency-Key: copy-playbook-20261118-0001"curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy \ -H "Authorization: Bearer <access_token>" \ -H "Idempotency-Key: copy-playbook-20261118-0001"
import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy",
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "copy-playbook-20261118-0001"},
)
print(response.json())const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Idempotency-Key": "copy-playbook-20261118-0001",
},
}
);
const data = await response.json();
console.log(data);req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/playbooks/7c9e6679-7425-40de-944b-e07fc1f90ae7/copy", nil)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "copy-playbook-20261118-0001")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response (201 Created)
Returns the playbook created by the copy in the same form as the response for getting your own playbook.
If you resend with the same Idempotency-Key, 200 OK is returned with the first copy (its current contents) in the same form. If the first copy has been deleted, 404 Not Found (playbook_not_found) is returned; send the request with a new key.
Response Example
{
"playbookId": "1d3f5a7b-9c2e-4a6c-8e0f-2b4d6f8a0c1e",
"ownerUserId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
"sourceConversationId": null,
"name": "Weekly report creation",
"description": "Generate a weekly report from sales data",
"category": "Reports",
"tags": [
"sales",
"weekly"
],
"steps": [
{
"title": "Data retrieval",
"description": "Retrieve sales data for the target period",
"guidance": [
"From Monday to Sunday of last week"
],
"success": "At least one record of data has been retrieved"
}
],
"isShared": false,
"isActive": true,
"shareRequestStatus": null,
"shareRequestNote": null,
"shareReviewNote": null,
"shareRequestedAt": null,
"usageCount": 0,
"copyCount": 0,
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"digest": "zP8MqAgVGbQF5em-ojsdO_8YZiLbt2J1XWTMsXjbO-E"
}
Error Responses
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | playbookId is not a UUID |
400 | idempotency_key_invalid | The format of Idempotency-Key is invalid |
403 | insufficient_scope | The assets:write scope is missing |
403 | forbidden | Called with a system integration token |
404 | playbook_not_found | The playbook does not exist, is not shared (even your own playbook returns 404 if it is not shared), or the copy created with the same Idempotency-Key has been deleted (send the request with a new key) |
409 | idempotency_conflict | A copy of a different playbook was sent with the same Idempotency-Key |
Search
Full-text search messages.
Endpoint List
| メソッド | エンドポイント | 説明 | Scope (SaaS) |
|---|---|---|---|
| GET | /v1/search/messages | Full-text search messages | chat:history |
Note: The Marketplace edition does not require scopes (authentication only).
GET/v1/search/messages
Full-text search messages. Messages of conversations of project steps and of archived conversations are not searched. Results are returned newest first by creation time (oldest first with order=asc), with cursor-based pagination.
Query Parameters
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
q | string | 必須 | Search query |
order | string | — | Sort order. "asc" (ascending) or "desc" (descending, default) |
limit | integer | — | Number of items per page (1-100). Defaults to 50. |
cursor | string | — | Cursor value for the next page. Pass the cursor from the previous response as is, with the same q and order. |
Request Example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=sales" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=sales" \ -H "Authorization: Bearer <access_token>"
import requests
from urllib.parse import quote
query = "sales"
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages",
headers={"Authorization": f"Bearer {token}"},
params={"q": query, "order": "desc"},
)
messages = response.json()["messages"]
for msg in messages:
print(f"{msg['title']}: {msg['text'][:50]}")const query = "sales";
const params = new URLSearchParams({ q: query, order: "desc" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?" + params,
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.messages.forEach((msg) => {
console.log(msg.title + ": " + msg.text);
});query := "sales"
req, _ := http.NewRequest("GET",
fmt.Sprintf("https://api.fd.agenticstar.tm.softbank.jp/api/v1/search/messages?q=%s&order=desc",
url.QueryEscape(query)),
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
messages | array | Array of search result messages (one page, up to limit) |
messages[].conversationId | string | Conversation ID (UUID) |
messages[].messageId | string | Unique identifier of the message |
messages[].text | string | Message body text |
messages[].title | string | Conversation title |
messages[].sender | string | Sender. "User" or "AI" |
messages[].createdAt | string | Creation date and time (ISO 8601) |
messages[].updatedAt | string | Last updated date and time (ISO 8601) |
messages[].matchedQueries | array | Array of matched search queries |
messages[].status | object | Message processing status |
messages[].status.processing | boolean | Whether the agent is currently processing |
messages[].status.unfinished | boolean | Whether the agent response was interrupted |
messages[].tasks | array | Array of tasks executed by the agent. See the Task object under GET /v1/conversations/:conversationId/messages for field definitions |
messages[].deliverables | array | Array of artifacts generated by the agent (included only when present) |
messages[].deliverables[].filename | string | Artifact file name |
messages[].deliverables[].filepath | string | Artifact file path |
messages[].deliverables[].source | string | "agent" (agent-generated) or "user" (user-uploaded) |
messages[].deliverables[].isPrimary | boolean | Whether it is a primary artifact |
messages[].deliverables[].createdAt | string | Creation date and time (ISO 8601 format). An empty string when unknown |
messages[].deliverables[].mimeType | string | MIME type (e.g., "application/pdf", "text/markdown"). "application/octet-stream" when it cannot be determined |
messages[].deliverables[].size | number? | File size (bytes). Omitted when 0 or below |
messages[].files | array? | Array of user-uploaded files. Included only when present for messages with sender: "User". The field structure matches the history API (fileId / mimeType / width? / height?). See GET /v1/conversations/:id/messages for details |
hasMore | boolean | true when there is a next page. When true, cursor is returned |
cursor | string | Cursor value for the next page. Included only when hasMore is true |
limitReached | boolean | true only when many messages match and only the most relevant results (up to 1,000 each for matches in the message text and in the agent's task progress) are covered. Not included otherwise. To search exhaustively, narrow the query |
Response Example
{
"messages": [
{
"conversationId": "550e8400-...",
"messageId": "msg-abc123",
"text": "Result of sales data analysis...",
"title": "Sales data analysis",
"sender": "AI",
"createdAt": "2026-03-14T10:30:00Z",
"updatedAt": "2026-03-14T10:35:00Z",
"matchedQueries": ["sales"],
"tasks": []
}
],
"hasMore": false
}
Error Response
| Status | Description |
|---|---|
400 | q parameter is missing or not a single string (for example, q specified more than once), order is not "asc" / "desc", limit is not an integer from 1 to 100, or cursor cannot be read |
403 | Missing chat:history scope |
501 | An environment where search is not configured (code: "search_not_configured") |
503 | Search is temporarily unavailable (code: "service_unavailable"). Retry after a while |
User
Retrieve, update user information, and change password.
Endpoint List
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /v1/user | Get user information |
| PATCH | /v1/user | Update user information |
| POST | /v1/user/password | Change password |
GET/v1/user
Get user information.
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
headers={"Authorization": f"Bearer {token}"},
)
user = response.json()
print(f"User: {user['username']} ({user['email']})")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const user = await response.json();
console.log("User: " + user.username + " (" + user.email + ")");req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var user map[string]interface{}
json.NewDecoder(resp.Body).Decode(&user)
fmt.Printf("User: %s (%s)\n", user["username"], user["email"])Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
userId | string | Unique identifier of the user |
email | string | Email address |
username | string | Username |
emailVerified | boolean | Email verification status |
createdAt | string | Account creation date and time (ISO 8601) |
isApproved | boolean | Account approval status |
role | string | User role |
organization | object | Organization (included only when set) |
organization.value | string | Organization code |
organization.label | string | Organization name |
jobType | object | Job type (included only when set) |
jobType.value | string | Job type code |
jobType.label | string | Job type name |
bio | string | Bio (included only when set) |
lastLoginAt | string | Last login date and time (ISO 8601, included only when present) |
Response Example
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "John Doe",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "Engineering Department" },
"jobType": { "value": "dev", "label": "Developer" },
"bio": "AI Engineer",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}
Error Response
| Status | code | Description |
|---|---|---|
500 | internal_error | The user information could not be retrieved (retry after a while) |
PATCH/v1/user
Update user information.
Request Body
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
username | string | — | Username. 2 to 50 characters; <, >, ", and ' cannot be used |
organization | string | — | Organization code. Up to 100 characters. It can be set only while it is not set, and only to a valid organization code. Changing an organization that is already set (including clearing it) returns 403. Ask an administrator to change it. If it is synced from the identity provider (IdP), change it in the IdP |
jobType | string | — | Job type code. Up to 100 characters. It can be set only while it is not set, and only to a valid job type code. Changing a job type that is already set (including clearing it) returns 403. Ask an administrator to change it. If it is synced from the identity provider (IdP), change it in the IdP |
bio | string | — | Bio. Up to 150 characters; <, >, ", and ' cannot be used |
Request Example
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" }'curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/user \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "username": "John Doe", "bio": "Engineering Department" }'import requests
response = requests.patch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
headers={"Authorization": f"Bearer {token}"},
json={"username": "John Doe", "bio": "Engineering Department"},
)
user = response.json()
print(f"Updated: {user['username']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
{
method: "PATCH",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
username: "John Doe",
bio: "Engineering Department",
}),
}
);
const user = await response.json();
console.log("Updated: " + user.username);payload := map[string]string{
"username": "John Doe",
"bio": "Engineering Department",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("PATCH",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)Response Fields (200 OK)
Returns the same user object as GET /v1/user (with updated values).
Response Example
{
"userId": "user-abc123",
"email": "tanaka@example.com",
"username": "John Doe",
"emailVerified": true,
"createdAt": "2026-03-10T09:00:00.000Z",
"isApproved": true,
"role": "user",
"organization": { "value": "eng", "label": "Engineering Department" },
"jobType": { "value": "dev", "label": "Developer" },
"bio": "Engineering Department",
"lastLoginAt": "2026-03-14T10:00:00.000Z"
}
Error Response
| Status | code | Description |
|---|---|---|
400 | invalid_parameter | No field to update was specified |
400 | invalid_body | The body is malformed JSON |
400 | invalid_parameter | Invalid input (username / organization / jobType / bio is not a string, has an invalid length or characters, or an organization / jobType being set for the first time is not a valid code) |
403 | affiliation_locked | An attempt was made to change an organization / jobType that is already set (including clearing it). Ask your administrator to change it. If it is synchronized from an IdP, change it in the identity provider (IdP) |
409 | conflict | Another update of the same user is being processed. Wait a moment and retry |
415 | unsupported_media_type | The Content-Type of the body is not application/json |
POST/v1/user/password
Change password.
Request Body
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
currentPassword | string | 必須 | Current password |
newPassword | string | 必須 | New password |
confirmPassword | string | 必須 | New password (confirmation) |
Request Example
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}'curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"currentPassword": "OldPass123!",
"newPassword": "NewPass456!",
"confirmPassword": "NewPass456!"
}'import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
headers={"Authorization": f"Bearer {token}"},
json={
"currentPassword": "OldPass123!",
"newPassword": "NewPass456!",
"confirmPassword": "NewPass456!",
},
)
data = response.json()
print(f"Password changed: {data['changed']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({
currentPassword: "OldPass123!",
newPassword: "NewPass456!",
confirmPassword: "NewPass456!",
}),
}
);
const data = await response.json();
console.log("Password changed: " + data.changed);payload := map[string]string{
"currentPassword": "OldPass123!",
"newPassword": "NewPass456!",
"confirmPassword": "NewPass456!",
}
body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/user/password",
bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
userId | string | Unique identifier of the user |
changed | boolean | Always true on successful password change |
Response Example
{ "userId": "user-abc123", "changed": true }
After you change the password, do not keep using the tokens obtained before the change; sign in again and get new tokens. An access token obtained before the change can still be used with the API until it expires.
Changing the password also signs the user out of the chat on every device, the next time they use it.
Error Response
| Status | Description |
|---|---|
400 | Missing required parameters, currentPassword / newPassword / confirmPassword is not a string, the body is malformed JSON (code: "invalid_body"), password validation failed, or the current password is incorrect |
415 | The body Content-Type is not application/json (code: "unsupported_media_type") |
401 | Authentication token is invalid |
403 | The user signs in with SSO (code: "federation_only_user"). SSO users cannot change their password with this API |
Master Data
Retrieve master data such as organizations and job types.
Endpoint List
| メソッド | エンドポイント | 説明 |
|---|---|---|
| GET | /v1/organizations | List organizations |
| GET | /v1/job-types | List job types |
| GET | /v1/personas | List personas |
GET/v1/organizations
List organizations. Inactive organizations are not included.
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/organizations \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/organizations \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/organizations",
headers={"Authorization": f"Bearer {token}"},
)
data = response.json()
for org in data["organizations"]:
print(f"{org['value']}: {org['label']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/organizations",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.organizations.forEach((org) => {
console.log(org.value + ": " + org.label);
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/organizations",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
organizations | array | Array of organization objects |
organizations[].value | string | Organization code |
organizations[].label | string | Organization name |
hasMore | boolean | Always false (pagination not supported) |
Response Example
{
"organizations": [
{ "value": "eng", "label": "Engineering Department" },
{ "value": "sales", "label": "Sales Department" }
],
"hasMore": false
}
Error Response
| Status | code | Description |
|---|---|---|
500 | internal_error | The list of organizations could not be retrieved (retry after a while) |
GET/v1/job-types
List job types. Inactive job types are not included.
Request Example
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types \2-H "Authorization: Bearer <access_token>"curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types",
headers={"Authorization": f"Bearer {token}"},
)
job_types = response.json()["jobTypes"]
for jt in job_types:
print(f"{jt['value']}: {jt['label']}")const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.jobTypes.forEach((jt) => {
console.log(jt.value + ": " + jt.label);
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/job-types",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
jobTypes | array | Array of job type objects |
jobTypes[].value | string | Job type code |
jobTypes[].label | string | Job type name |
hasMore | boolean | Always false (pagination not supported) |
Response Example
{
"jobTypes": [
{ "value": "dev", "label": "Developer" },
{ "value": "pm", "label": "Project Manager" }
],
"hasMore": false
}
Error Response
| Status | code | Description |
|---|---|---|
500 | internal_error | The list of job types could not be retrieved (retry after a while) |
GET/v1/personas
Retrieves the list of personas (agent response personalities). Use a returned personaKey to specify a persona in Chat / MCP / A2A.
Query Parameters
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
locale | string | — | Platform default language | Display language for name / description (for example "ja", "en"). An unknown value or a non-string value does not return 400; the platform default language is used |
Request example
1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas?locale=ja" \2-H "Authorization: Bearer <access_token>"curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas?locale=ja" \ -H "Authorization: Bearer <access_token>"
import requests
response = requests.get(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas",
headers={"Authorization": f"Bearer {token}"},
params={"locale": "ja"},
)
for persona in response.json()["personas"]:
print(persona["personaKey"], persona["name"])const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas?locale=ja",
{
headers: { "Authorization": "Bearer " + accessToken },
}
);
const data = await response.json();
data.personas.forEach((persona) => {
console.log(persona.personaKey + " " + persona.name);
});req, _ := http.NewRequest("GET",
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/personas?locale=ja",
nil)
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["personas"])Response Fields (200 OK)
| Field | Type | Description |
|---|---|---|
locale | string | The resolved locale. A persona with no content in the requested language is returned with its content in another language, in the order English, Japanese, then other languages |
personas | array | Array of persona objects |
personas[].personaKey | string | Persona identifier (specify as personaKey in Chat / MCP / A2A) |
personas[].name | string | Persona display name |
personas[].description | string | Persona description |
hasMore | boolean | Always false (pagination not supported) |
Response Example
{
"locale": "en",
"personas": [
{ "personaKey": "concise", "name": "Concise", "description": "Answers concisely, focusing on key points" }
],
"hasMore": false
}
Error Response
| Status | code | Description |
|---|---|---|
500 | internal_error | The list of personas could not be retrieved (retry after a while) |
Projects
The project APIs are in the User API Reference (Projects). 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. Also returned for a token of a user whose use was suspended by an administrator (see "Suspended users" below) |
403 Forbidden | No access permission to the resource. Also returned when an administrator restricts where the public API can be called from and the IP address of the caller is not in the allowed list (error.code is ip_not_allowed) |
404 Not Found | Resource does not exist, or the path or method is not defined (405 is not returned) |
409 Conflict | Operation conflict, such as the resource currently being processed |
409 Conflict | A person with the organization operations role (the "Operator" role assigned in "Admin Roles" in the admin console) who does not take part in the project called an operation that role cannot use (error.code is forbidden_role). It does not clear by waiting. For an owner-only operation, ask an owner of the project to do it. For other operations, ask an owner to add you to the project; you can then call them as your project role allows |
413 Payload Too Large | Request body exceeds the size limit |
415 Unsupported Media Type | The request body format (Content-Type) is not supported |
429 Too Many Requests | Rate limit or concurrent-run limit exceeded. error.type is rate_limit_error, and error.code depends on the endpoint (for example monthly_quota_exceeded for the monthly limit and too_many_active_runs for concurrent project runs). Please wait and retry. |
500 Internal Server Error | Internal server error |
502 Bad Gateway | Communication error with upstream services (authentication / chat backends, etc.) |
503 Service Unavailable | Service temporarily unavailable |
504 Gateway Timeout | Upstream service response timeout |
Error Response Format
All error responses are returned in the following common structure.
| Field | Type | Description |
|---|---|---|
error.type | string | Error classification. One of: "invalid_request_error", "authentication_error", "insufficient_scope_error", "forbidden_error", "not_found_error", "conflict_error", "payload_too_large_error", "rate_limit_error", "server_error", "upstream_error" |
error.message | string | Human-readable error message |
error.code | string | Machine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token") |
error.param | string | The parameter that caused the error. Included only for validation errors |
error.reason | string | The kind of reason for the refusal. Included only for 409 (definition_invalid) of the project APIs |
error.suggested_action | string | Recommended action to take. Included only for some errors |
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}
Suspended users
A call with the token of a user whose use was suspended by an administrator returns 401 Unauthorized. error.code is account_suspended.
The following APIs do not check whether the user is suspended: GET /v1/organizations, GET /v1/job-types, GET /v1/personas, GET /v1/user, PATCH /v1/user, and the MCP tools list_personas and cancel_chat (when no task is in progress). They can still be called after the suspension until the access token expires. A suspended user cannot refresh the access token.
When the Request Is Stopped Before Reaching the API
If a layer in front of the API (such as a security inspection) returns an HTML error page, the response is replaced with JSON in the common format above. In that case, error.code is one of the following.
| Status | error.code | Description |
|---|---|---|
| 403 | waf_blocked | The request was stopped by a security inspection in front of the API. If the request is legitimate, contact support with error.reference (or the x-request-id response header if it is not present) |
| 4xx and 5xx other than 403 | upstream_api_error | The request was rejected by, or caused an error in, a layer in front of the API. If this continues, contact support with error.reference (or the x-request-id response header if it is not present) |
| Field | Type | Description |
|---|---|---|
error.reference | string | Reference number for a request stopped before reaching the API. Include it when contacting support. Omitted when no value is available |
{
"error": {
"type": "forbidden_error",
"message": "The request was blocked by a web application firewall before it reached the API.",
"code": "waf_blocked",
"suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
"reference": "20261018T012345Z-0123456789abcdef"
}
}