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. Default values and limits vary by endpoint
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)

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=2026-03-14T10:30:00.000Z" \
  -H "Authorization: Bearer <access_token>"

Currently, cursor-based pagination is supported for GET /v1/conversations. For other endpoints, hasMore is always false.

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.
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)
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
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
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	25	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": "2026-03-14T10:30:00.000Z"
}

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.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
limit	integer	—	Maximum number of items to retrieve
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	Always false (pagination not supported)

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](/docs/api/guide/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)

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
}

Error Response

Status	Description
400	Invalid conversationId format
403	Missing chat:history scope
404	Conversation not found

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

Query Parameters

Parameter	Type	Default	Description
limit	integer	—	Maximum number of items to retrieve. All items are returned when omitted
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	Always false (pagination not supported)

Response Example

JSON

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

Error Response

Status	Description
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

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.

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	Missing chat:exec scope
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

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](#get-messages) for field definitions
messages[].deliverables	array	Array of artifacts generated by the agent (included only when present)
messages[].deliverables[].filename	string	Artifact file name
messages[].deliverables[].filepath	string	Artifact file path
messages[].deliverables[].source	string	"agent" (agent-generated) or "user" (user-uploaded)
messages[].deliverables[].isPrimary	boolean	Whether it is a primary artifact
messages[].deliverables[].createdAt	string	Creation date and time (ISO 8601 format)
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](#get-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"
  }
}