User API Reference

Reference for user-facing API endpoint specifications and error codes. For administrator-only APIs, see the Admin API Reference.

Base URL

All API requests are sent to the following base URLs.

SaaS

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

Marketplace

https://<your-domain>/api

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

Edition-specific API Support

Each endpoint section has a badge (SaaS / Marketplace) indicating which editions support it. The summary is below.

Endpoint group	SaaS	Marketplace	Primary use
Chat	✅	✅	OpenAI-compatible SSE
Conversation Management	✅	✅	List / read messages / delete / update
File Management	✅	✅	Upload / download / delete
Artifact Retrieval	✅	✅	Retrieve files generated by agents
Search	✅	✅	Message search
Library	✅	—	Prompt templates / shared assets
User	✅	—	User information lookup
Master Data	✅	—	Organization / job type master

note

On the Marketplace edition, the Chat API requires the agentId header and is fixed to stream: true. See the Marketplace Quickstart for details.

Authentication

All API requests must include a Bearer token in the Authorization header.

Authorization: Bearer <access_token>

If the token is invalid or missing, 401 Unauthorized is returned. Some endpoints require additional scopes. If the required scopes are missing, 403 Forbidden is returned.

For details on obtaining tokens and scopes, see the Authentication Guide and — depending on your edition — the Authentication API Reference (SaaS) or the Authentication API Reference (MP).

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 fetching the next page. Pass the cursor value from the previous response as-is
order	string	Sort order. "asc" (ascending) or "desc" (descending, default). Supported only by some endpoints

The response includes a hasMore field. When true, pass the cursor value to the next request to retrieve the next page.

curl

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

# Page 2 (using the cursor value from the response)
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/conversations?limit=10&cursor=<cursor>" \
  -H "Authorization: Bearer <access_token>"

Cursor-based pagination is supported by the list endpoints for conversations, messages, files, library, skills, and playbooks. The cursor is an opaque value: do not interpret its contents; pass the value from the previous response as-is to the next request.

Chat SaaS Marketplace

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

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

SSE Streaming Guide

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

View guide

Endpoint List

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

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

POST/v1/chat/completions

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

Request Headers

ヘッダー	必須	説明
Authorization	必須	Bearer <access_token>
Content-Type	必須	application/json

Request Body

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

Edition-Specific Parameters

SaaS

agentLevel	string	"default" or "high_performance". Defaults to "default" when omitted.
agentMode	boolean	Enable/disable agent mode. Defaults to true when omitted.
privateMode	boolean	Enable/disable private mode. Defaults to false when omitted.
reportMode	string	"with" (default) or "without". Controls whether a work report is generated on completion.
personaKey	string	Persona (response personality) to apply. Specify a personaKey returned by `GET /v1/personas`. Omit to apply no persona.
playbookId	string	Playbook (predefined procedure) to apply. Specify a playbookId returned by `GET /v1/playbooks`. Omit to apply no playbook. Returns 400 if the ID does not exist or has been deactivated.
skillIds	array	Array of skill IDs to load into the agent (up to 10). Specify skillId values returned by `GET /v1/skills`. Returns 400 if 11 or more are specified. IDs that do not exist or are unavailable are ignored, and execution continues with the remaining skills.
outputFormat	string	Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept). "markdown" preserves Markdown as-is.

Marketplace

agentId	string	The ID of the agent to use (required).
outputFormat	string	Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept). "markdown" preserves Markdown as-is.

Message Object

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

Content Parts (Array Format)

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

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

Request Example

Create chat completion

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

Response Headers

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

SSE Response Format

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

SSE Event Flow

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

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

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

4. data: [DONE]

Responses are delivered via SSE (Server-Sent Events) streaming. Each chunk is in OpenAI-compatible ChatCompletionChunk format. For details on the connection lifecycle, response objects, agent extension fields, and error handling, see the Streaming Guide.

Response Example

SSE

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

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

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

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

data: [DONE]

Error Response

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

Status	Description
400	Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input_file parts in a single request). Or the specified conversationId is archived (code: "conversation_archived")
403	Missing chat:exec scope
404	The specified input_file fileId or filepath is not found
409	The specified conversation is currently being processed

GET/v1/chat/completions/:conversationId

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

Path Parameters

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

Request Example

Resume SSE stream

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

Response (200 OK)

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

Error Response

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

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

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

Path Parameters

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

Request Body (optional)

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

Request Example

Cancel chat

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

Status	Description
400	Invalid conversationId, or the conversation is archived (code: "conversation_archived")
403	Missing chat:exec scope
404	Conversation not found

Conversation Management SaaS Marketplace

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

Endpoint List

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

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

Operations on archived conversations

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

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

GET/v1/conversations

List conversations. Supports cursor-based pagination.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of items to retrieve (1-100)
cursor	string	—	Cursor for fetching the next page (cursor value from the previous response)
order	string	"desc"	"asc" or "desc"
title	string	—	Filter by title
mode	string	"active"	"active" (regular conversations) or "archive" (archived conversations). Switching mode queries a different data store, so cursor cannot be carried over

Request Example

List conversations

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

Response Fields (200 OK)

Field	Type	Description
conversations	array	Array of conversation objects
conversations[].conversationId	string	Unique identifier of the conversation (UUID)
conversations[].title	string	Conversation title
conversations[].createdAt	string	Creation date and time (ISO 8601)
conversations[].updatedAt	string	Last updated date and time (ISO 8601)
conversations[].archived	boolean?	Whether archived. Always true when retrieved via mode=archive. When mode=active returns this field as true, it is only because the conversation remained in archive state but was returned by the active list — usually omitted
hasMore	boolean	Whether the next page exists
cursor	string	Cursor for fetching the next page. Included only when hasMore is true

Response Example

JSON

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

Error Response

Status	Description
400	Invalid limit parameter (outside the range of 1-100), or mode is not "active" / "archive"
403	Missing chat:history scope

GET/v1/conversations/:conversationId/messages

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

Path Parameters

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

Query Parameters

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

Request Example

Get messages

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

Response Fields (200 OK)

Field	Type	Description
messages	array	Array of message objects
messages[].conversationId	string	Conversation ID (UUID)
messages[].messageId	string	Unique identifier of the message
messages[].sender	string	Sender. "User" or "AI"
messages[].text	string	Message body text
messages[].createdAt	string	Creation date and time (ISO 8601)
messages[].updatedAt	string	Last updated date and time (ISO 8601)
messages[].status	object	Message processing status
messages[].status.processing	boolean	Whether the agent is currently processing
messages[].status.unfinished	boolean	Whether the agent response was interrupted
messages[].tasks	array	Array of tasks executed by the agent (see below)
messages[].deliverables	array	Array of artifacts generated by the agent. Included only when present
messages[].deliverables[].filename	string	Artifact file name
messages[].deliverables[].filepath	string	Artifact file path
messages[].deliverables[].source	string	"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimary	boolean	Whether it is a primary artifact
messages[].deliverables[].createdAt	string	Creation date and time (ISO 8601 format)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted when it cannot be determined
messages[].deliverables[].size	number?	File size (bytes). Omitted when 0 or below
messages[].files	array?	Array of user-uploaded files. Included only when present for messages with sender: "User"
messages[].files[].fileId	string	Unique identifier of the file (UUID)
messages[].files[].mimeType	string	MIME type (e.g., "image/png", "application/pdf")
messages[].files[].width	number?	Image width in pixels. Only for image files
messages[].files[].height	number?	Image height in pixels. Only for image files
messages[].archived	boolean?	true only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with GET /v1/conversations?mode=archive
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Task Object

Field	Type	Description
messageId	string	ID of the message the task belongs to
conversationId	string	ID of the conversation the task belongs to
callId	string?	Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call
actionType	string	Type of task (e.g., tool execution, code generation)
title	string?	Task title. Omitted when not present
description	string?	Task description. Omitted when not present
status	string	Task status. One of: "in_progress" / "completed" / "failed" / "error" / "pending"
content	string?	Task execution result text. Omitted when not present
metadata	object?	Auxiliary information that varies by actionType (sub_event_type, url, filepath, etc.). See the Streaming Guide for details
files	array?	Files related to the task (filename / size / filepath / mimeType?. mimeType is omitted when it cannot be determined). The array itself is omitted when there are no related files
timestamp	number	Timestamp of task execution (Unix milliseconds)
createdAt	string	Creation date and time (ISO 8601)
updatedAt	string	Last updated date and time (ISO 8601)

UI resources (tasks[].metadata.uiResource)

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

The object has the same structure as in SSE. For field details, see Streaming Guide — delta.uiResource. The alternative text is in content of the same task (in SSE it is delta.content of the same chunk).

Contents of metadata	Meaning
uiResource only	Display-only UI. No user reply is expected.
uiResource + interaction_type	UI that asks for a reply. interaction_type is "choice" or "question". This combination occurs only with origin: "first-party".
interaction_type only	A reply is requested but no UI is included. interaction_type is "choice" | "confirmation" | "question". The reply instructions are in content of the same task.
options	Array of choices (up to 10, each up to 200 characters). May be present independently of whether interaction_type is set.

Discrimination differs from SSE

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

JSON

{
  "status": "completed",
  "content": "Sales have grown for three consecutive quarters.",
  "metadata": {
    "uiResource": {
      "type": "html",
      "origin": "first-party",
      "altText": "Sales have grown for three consecutive quarters.",
      "uri": "ui://widget/chart",
      "server_name": "agentic-star-widgets",
      "tool_name": "widget_chart",
      "tool_call_id": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
      "mime_type": "text/html;profile=mcp-app"
    }
  },
  "timestamp": 1788007347240
}

size is not included in history and search responses.

Safely ignore unknown fields

Future implementations may add new fields to actionType / metadata. Client implementations should safely ignore any fields not listed in this table. For detailed metadata structure, refer to the Streaming Guide — Task data model.

Response Example

JSON

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

Pagination

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

curl

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

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

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

Using the cursor

The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if messages are added or removed while you are paging.

Error Response

Status	Description
400	Invalid conversationId format
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
403	Missing chat:history scope
404	Conversation not found

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

Retrieves the HTML of a UI resource. Pass the tool_call_id found in SSE delta.uiResource, in tasks[].metadata.uiResource of history and search, or in the A2A and MCP responses.

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

The response is JSON

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

Required Scope

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

Path Parameters

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

Request Example

Get UI resource

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

Response Fields (200 OK)

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

JSON

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

Error Response

Use code to decide whether a retry makes sense.

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

Notes on rendering

This endpoint returns the HTML as a string, and rendering happens in your own application. For whether you need a sandbox and how it differs by origin, see Streaming Guide — Notes on rendering.

PATCH/v1/conversations/:conversationId

Update the title of a conversation.

Path Parameters

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

Request Body

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

Request Example

Update conversation

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

Status	Description
400	title is missing, empty, or exceeds 200 characters, or the conversation is archived (code: "conversation_archived")
403	Missing chat:history scope
404	Conversation not found

DELETE/v1/conversations/:conversationId

Delete a conversation.

Path Parameters

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

Request Example

Delete conversation

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

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

POST/v1/conversations/:conversationId/restore

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

Path Parameters

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

Request Example

Restore archived conversation

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

Status	Description
400	Invalid conversationId
403	Missing chat:history scope
404	No matching conversation in archive, or it is already active (archive state is not distinguished)

File Management SaaS Marketplace

Upload, retrieve, and delete files.

Endpoint List

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

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

POST/v1/files

Upload a file.

Request Body (multipart/form-data)

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

Request Example

Upload file

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

Response Fields (201 Created)

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

Response Example

JSON

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

Error Response

Status	Description
400	file or filename parameter is missing, file size exceeds 512 MB, or the uploaded image file is corrupted or invalid
403	Missing chat:file scope

GET/v1/files

List files. Cursor-based pagination is supported.

Query Parameters

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

Request Example

List files

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

Response Fields (200 OK)

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

Response Example

JSON

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

Pagination

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

curl

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

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

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

Using the cursor

The cursor represents a position in the result set. Do not change order while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if files are added or removed while you are paging.

Error Response

Status	Description
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
403	Missing chat:file scope

GET/v1/files/:file_id/content

Download a file.

Path Parameters

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

Request Example

Download file

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

Response (200 OK)

The file binary data is returned as a stream.

Response Header	Description
Content-Type	MIME type of the file
Content-Length	File size (bytes)
Content-Disposition	attachment; filename="filename"

Error Response

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

DELETE/v1/files/:file_id

Delete a file.

Path Parameters

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

Request Example

Delete file

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

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

Artifact Retrieval SaaS Marketplace

Retrieve artifact files generated by the agent.

Endpoint List

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

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

GET/v1/files/proxy

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

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

Query Parameters

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

Request Example

Get artifact file

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

Response (200 OK)

The artifact file binary data is returned as a stream.

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

Error Response

Status	Description
400	path parameter is missing or has an invalid format
403	None of chat:exec / a2a:all / mcp:all is present
404	File not found

Library SaaS

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

Endpoints

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/library	List library files	chat:exec

GET/v1/library

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

Query Parameters

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

Response Fields (200 OK)

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

Response Example

JSON

{
  "files": [
    {
      "filename": "report.xlsx",
      "filepath": "/path/to/report.xlsx",
      "source": "agent",
      "createdAt": "2026-03-14T10:30:00.000Z",
      "updatedAt": "2026-03-14T10:30:00.000Z",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size": 20480,
      "conversationId": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "hasMore": false
}

Error Responses

Status	Description
400	Invalid limit (out of 1–100 range), cursor, or source (other than "agent" / "user")
403	Missing chat:exec scope

Skills SaaS

Lists the skills that can be specified when running a chat. Use a returned skillId in the Chat skillIds parameter to load skills into the agent.

Use GET /v1/skills for skills you registered yourself, and GET /v1/skills/shared for skills shared publicly by other users. Shared skills can be specified in skillIds directly without copying them.

Endpoint List

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/skills	List your skills	chat:exec
GET	/v1/skills/shared	List shared skills	chat:exec

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
limit	integer	50	Number of items per page (1-100)
cursor	string	—	Cursor for the next page (the cursor value from the previous response)

Response Fields (200 OK)

Field	Type	Description
skills	array	Array of skill objects
skills[].skillId	string	Skill ID (specify this in the Chat skillIds parameter)
skills[].name	string	Skill name
skills[].description	string?	Skill description
skills[].category	string?	Category
skills[].tags	array	Array of tags. An empty array when unset
skills[].isShared	boolean	Whether you share the skill publicly
skills[].isActive	boolean	Whether the skill is active
skills[].createdAt	string	Creation time (ISO 8601)
skills[].updatedAt	string	Last update time (ISO 8601)
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Response Example

JSON

{
  "skills": [
    {
      "skillId": "3f2a4b6c-1d2e-4f5a-8b9c-0d1e2f3a4b5c",
      "name": "release-notes",
      "description": "Generate release notes",
      "category": "devops",
      "tags": ["ci"],
      "isShared": false,
      "isActive": true,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}

Pagination

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

curl

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

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

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

Using the cursor

The cursor represents a position in the result set. Do not change active_only while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if skills are added or removed while you are paging.

Error Responses

Status	Description
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
403	Missing chat:exec scope

GET/v1/skills/shared

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

Query Parameters

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

Response Fields (200 OK)

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

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

Response Example

JSON

{
  "skills": [
    {
      "skillId": "9c8b7a6d-5e4f-4a3b-8c1d-2e3f4a5b6c7d",
      "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	Missing chat:exec scope

Playbooks SaaS

Lists your playbooks. Use a returned playbookId in the Chat playbookId parameter to run the agent with a predefined procedure.

Endpoint List

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/playbooks	List playbooks	chat:exec

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
limit	integer	50	Number of items per page (1-100)
cursor	string	—	Cursor for the next page (the cursor value from the previous response)

Response Fields (200 OK)

Field	Type	Description
playbooks	array	Array of playbook objects
playbooks[].playbookId	string	Playbook ID (specify this in the Chat playbookId parameter)
playbooks[].name	string	Playbook name
playbooks[].description	string?	Description
playbooks[].category	string?	Category
playbooks[].tags	array	Array of tags
playbooks[].steps	array	Array of steps
playbooks[].steps[].title	string	Step title
playbooks[].steps[].description	string	Step description
playbooks[].steps[].guidance	array?	Array of supplementary instructions
playbooks[].steps[].success	string?	Completion criteria
playbooks[].sourceConversationId	string?	ID of the conversation the playbook was created from
playbooks[].isShared	boolean	Whether the playbook is shared
playbooks[].isActive	boolean	Whether the playbook is active
playbooks[].usageCount	number	Number of times used
playbooks[].copyCount	number	Number of times copied
playbooks[].createdAt	string	Creation time (ISO 8601)
playbooks[].updatedAt	string	Last update time (ISO 8601)
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Response Example

JSON

{
  "playbooks": [
    {
      "playbookId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Weekly report",
      "description": "Generate a weekly report from sales data",
      "category": "Reporting",
      "tags": ["sales", "weekly"],
      "steps": [
        {
          "title": "Fetch data",
          "description": "Fetch sales data for the target period",
          "guidance": ["From Monday to Sunday of the previous week"],
          "success": "At least one record was fetched"
        }
      ],
      "sourceConversationId": "550e8400-e29b-41d4-a716-446655440000",
      "isShared": false,
      "isActive": true,
      "usageCount": 12,
      "copyCount": 0,
      "createdAt": "2026-08-01T03:12:45.123Z",
      "updatedAt": "2026-08-05T09:00:00.000Z"
    }
  ],
  "hasMore": false
}

Pagination

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

curl

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

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

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

Using the cursor

The cursor represents a position in the result set. Do not change active_only while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.

Items may also be duplicated or skipped across pages if playbooks are added or removed while you are paging.

Error Responses

Status	Description
400	limit is not an integer between 1 and 100
400	cursor is invalid (not a value from a previous response)
403	Missing chat:exec scope

Search SaaS Marketplace

Full-text search messages.

Endpoint List

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

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

GET/v1/search/messages

Full-text search messages.

Query Parameters

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

Request Example

Search messages

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

Response Fields (200 OK)

Field	Type	Description
messages	array	Array of search result messages (up to 50)
messages[].conversationId	string	Conversation ID (UUID)
messages[].messageId	string	Unique identifier of the message
messages[].text	string	Message body text
messages[].title	string	Conversation title
messages[].sender	string	Sender. "User" or "AI"
messages[].createdAt	string	Creation date and time (ISO 8601)
messages[].updatedAt	string	Last updated date and time (ISO 8601)
messages[].matchedQueries	array	Array of matched search queries
messages[].status	object	Message processing status
messages[].status.processing	boolean	Whether the agent is currently processing
messages[].status.unfinished	boolean	Whether the agent response was interrupted
messages[].tasks	array	Array of tasks executed by the agent. See the Task object under GET /v1/conversations/:conversationId/messages for field definitions
messages[].deliverables	array	Array of artifacts generated by the agent (included only when present)
messages[].deliverables[].filename	string	Artifact file name
messages[].deliverables[].filepath	string	Artifact file path
messages[].deliverables[].source	string	"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimary	boolean	Whether it is a primary artifact
messages[].deliverables[].createdAt	string	Creation date and time (ISO 8601 format)
messages[].deliverables[].mimeType	string?	MIME type (e.g., "application/pdf", "text/markdown"). Omitted when it cannot be determined
messages[].deliverables[].size	number?	File size (bytes). Omitted when 0 or below
messages[].files	array?	Array of user-uploaded files. Included only when present for messages with sender: "User". The field structure matches the history API (fileId / mimeType / width? / height?). See GET /v1/conversations/:id/messages for details
hasMore	boolean	Always false (pagination not supported)

Response Example

JSON

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

Error Response

Status	Description
400	q parameter is missing
403	Missing chat:history scope

User SaaS

Retrieve, update user information, and change password.

Endpoint List

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

GET/v1/user

Get user information.

Request Example

Get user

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

Response Fields (200 OK)

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

Response Example

JSON

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

PATCH/v1/user

Update user information.

Request Body

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

Request Example

Update user

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

Status	Description
400	No fields specified for update

POST/v1/user/password

Change password.

Request Body

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

Request Example

Change password

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

Response Fields (200 OK)

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

Response Example

JSON

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

Error Response

Status	Description
400	Missing required parameters or password validation failed
401	Authentication token is invalid or current password is incorrect

Master Data SaaS

Retrieve master data such as organizations and job types.

Endpoint List

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

GET/v1/organizations

List organizations. Inactive organizations are not included.

Request Example

List organizations

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

Response Fields (200 OK)

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

Response Example

JSON

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

GET/v1/job-types

List job types. Inactive job types are not included.

Request Example

List job types

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

Response Fields (200 OK)

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

Response Example

JSON

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

GET/v1/personas

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

Query Parameters

Parameter	Type	Default	Description
locale	string	Platform default language	Display language for name / description (e.g., "ja", "en")

Response Fields (200 OK)

Field	Type	Description
locale	string	The resolved locale
personas	array	Array of persona objects
personas[].personaKey	string	Persona identifier (specify as personaKey in Chat / MCP / A2A)
personas[].name	string	Persona display name
personas[].description	string	Persona description
hasMore	boolean	Always false (pagination not supported)

Response Example

JSON

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

Error Responses

HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

Status	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Token is invalid or missing
403 Forbidden	No access permission to the resource
404 Not Found	Resource does not exist
409 Conflict	Operation conflict, such as the resource currently being processed
413 Payload Too Large	Request body exceeds the size limit
429 Too Many Requests	Rate limit exceeded. error.type is server_error and error.code is rate_limit_exceeded. 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", "server_error", "upstream_error"
error.message	string	Human-readable error message
error.code	string	Machine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token")
error.param	string	The parameter that caused the error. Included only for validation errors
error.suggested_action	string	Recommended action to take. Included only for some errors

JSON

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