System Integration API Reference

API reference for user management, log viewing, master data management, shared memory search, and project operations. For end-user-facing APIs (Chat / Conversations / Files / Search / public master data), see the User API Reference. For MCP / A2A connection methods, see the Connection Methods Guide.

SaaS Edition Only

All endpoints documented in this reference are available only in the SaaS edition. On the Marketplace edition, administrative operations are performed exclusively through the Admin Console.

Base URL

All API requests are sent to the following base URL.

SaaS

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

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

Authentication

All API requests require 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 scope is missing, 403 Forbidden is returned.

For details on obtaining tokens and scope assignment, see the Authentication Guide and Authentication API Reference (SaaS).

Pagination

List retrieval endpoints use one of two schemes. Which one applies is fixed per endpoint. Organization and job type lists do not support pagination and always return all records.

Page-based

Parameter	Type	Description
limit	integer	Number of items per page. 1 to 100 (default 25)
page	integer	Page number. 1 or greater (default 1)

Responses include total, limit, page, and hasMore. When hasMore is true, increase page by 1 to retrieve the next page.

curl

# Page 1
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=1" \
  -H "Authorization: Bearer <access_token>"

# Page 2
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=2" \
  -H "Authorization: Bearer <access_token>"

Endpoints using this scheme: the users list and the log lists (audit logs, LLM logs, LLM Gateway logs, access logs, and guardrail alerts).

Cursor-based

Parameter	Type	Description
limit	integer	Number of items per page (1-100). Defaults to 50
cursor	string	Cursor value for the next page. Pass back the cursor from the previous response as-is

Responses include hasMore. When it is true, pass the cursor value in the next request to retrieve the next page. Treat cursor as opaque: do not interpret it, just pass the previous value back.

The endpoint using this scheme is the project list. It does not use page (it is ignored if specified).

Request handling

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

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

Shared Memory SaaS

Searches shared memory (knowledge) based on organization and job role.

Endpoint List

メソッド	エンドポイント	説明	スコープ
POST	/v1/admin/memory/query	Search shared memory	sharedmemory:query

POST/v1/admin/memory/query

Search shared memory.

Request Body

パラメータ	型	必須	説明
query	string	必須	Search query (max 500 characters)
orgId	string	—	Organization ID (max 100 characters). If specified, organization-scoped memory is included in the search
jobRole	string	—	Job role (max 100 characters). If specified, role-scoped memory is included in the search

Request Example

Search shared memory

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{"query": "How to create a sales report", "orgId": "sales"}'

Response Fields (200 OK)

Field	Type	Description
memories	array	Array of memory objects
memories[].text	string	Memory content text
memories[].type	string	"knowledge"
memories[].scope	string	One of "organization", "role", or "global"
memories[].createdAt	string | null	Creation date and time (ISO 8601)
memories[].score	number?	Relevance score. Field is omitted when score is not available

Response Headers

Header	Description
X-RateLimit-Limit	Monthly request limit
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Reset time (start of next month, ISO 8601)

Response Example

JSON

{
  "memories": [
    {
      "text": "Sales reports can be created from the 'Monthly Reports' tab in the dashboard",
      "type": "knowledge",
      "scope": "organization",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "score": 0.85
    }
  ]
}

Error Response

Status	Description
400	query is missing, empty, or exceeds 500 characters, or the body is malformed JSON (code: "invalid_body")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	sharedmemory:query scope is missing
429	Monthly quota exceeded (error.type: rate_limit_error, error.code: monthly_quota_exceeded)
502	Communication error with an upstream service (error.type: upstream_error)
504	Upstream service response timeout (error.type: upstream_error, error.code: upstream_timeout)

When the search succeeds with no matches, 200 is returned with an empty memories array. Upstream failures return 502 / 504 instead of an empty array, so an empty array in a 200 response does not indicate a failure.

User Management SaaS

List, delete, change role, approve, and revoke approval of users.

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/users	List users	users:read / users:manage
DELETE	/v1/admin/users/:userId	Delete user	users:manage
PUT	/v1/admin/users/:userId/role	Change user role	users:manage
POST	/v1/admin/users/:userId/approve	Approve user	users:manage
POST	/v1/admin/users/:userId/reject	Revoke user approval	users:manage

GET/v1/admin/users

List users. Supports page-based pagination. Either the users:read or users:manage scope is required (users:manage includes users:read permissions).

Query Parameters

パラメータ	型	必須	説明
limit	integer	—	Number of items to fetch (1–100, default: 25)
page	integer	—	Page number (1 or more, default: 1)
role	string	—	Role filter. "admin" can be specified
is_approved	string	—	Approval status filter. "true" or "false"
search	string	—	Search string (max 100 characters). Searches by email address, etc.
organization	string	—	Organization code filter (max 50 characters; alphanumeric, hyphen, underscore)
job_type	string	—	Job type code filter (max 50 characters; alphanumeric, hyphen, underscore)

Request Example

List users

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

Response Fields (200 OK)

Field	Type	Description
users	array	Array of user objects
users[].userId	string	User ID
users[].email	string	Email address
users[].username	string	Username
users[].emailVerified	boolean	Email verification status
users[].role	string	Role ("admin" or "user")
users[].status	string	Status ("unverified", "pending", or "approved")
users[].organization	object?	Organization (value: code, label: name). Field is omitted if not set
users[].jobType	object?	Job type (value: code, label: name). Field is omitted if not set
users[].bio	string?	Self-introduction. Field is omitted when not set
users[].createdAt	string	Creation date and time (ISO 8601)
users[].lastLoginAt	string?	Last login date and time (ISO 8601). Field is omitted if the user has never logged in
total	integer	Total count
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether the next page exists

Example Response (200 OK)

JSON

{
  "users": [
    {
      "userId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "email": "user1@example.com",
      "username": "user1@example.com",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "createdAt": "2026-04-19T13:02:26.198Z"
    },
    {
      "userId": "90b40fd8-a6b8-42b8-ab61-f3b674169b43",
      "email": "user2@example.com",
      "username": "user2",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "organization": { "value": "sales", "label": "Sales" },
      "jobType": { "value": "engineer", "label": "Engineer" },
      "createdAt": "2026-04-17T07:09:47.484Z"
    },
    {
      "userId": "463e2c25-5a80-4362-b77e-941df96fb1f2",
      "email": "admin@example.com",
      "username": "admin@example.com",
      "emailVerified": true,
      "role": "admin",
      "status": "approved",
      "createdAt": "2026-04-17T07:02:41.015Z",
      "lastLoginAt": "2026-04-17T07:18:17.488Z"
    }
  ],
  "total": 132,
  "limit": 3,
  "page": 1,
  "hasMore": true
}

Error Response

Status	Description
400	Invalid query parameters
403	users:read or users:manage scope is missing

DELETE/v1/admin/users/:userId

Delete a user. Requires users:manage scope.

Path Parameters

パラメータ	型	必須	説明
userId	string	必須	User ID

Request Example

Delete user

1curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID \
2-H "Authorization: Bearer <access_token>"

Response Example (200 OK)

JSON

{ "userId": "abc123", "deleted": true }

Error Responses

Status	Description
403	Missing users:manage scope
404	The specified user was not found (including already deleted)

PUT/v1/admin/users/:userId/role

Change a user's role. Only approved users can have their role changed.

Behavior on Role Change

• When demoting to user: The target user's existing sessions are invalidated, requiring them to log in again.
• When promoting to admin: The target user's existing sessions continue, and the new permissions take effect from the next API call.

Path Parameters

パラメータ	型	必須	説明
userId	string	必須	User ID

Request Body

パラメータ	型	必須	説明
role	string	必須	The role to change to. "admin" or "user"

Request Example

Change user role

1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/role \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{"role": "admin"}'

Response Example (200 OK)

JSON

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

Error Response

Status	Description
400	role is missing or invalid, the body is malformed JSON (code: "invalid_body"), or the target user is not approved
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	users:manage scope is missing
404	User not found

POST/v1/admin/users/:userId/approve

Approve a user. Only users with status "pending" can be approved.

note

When approval succeeds, an approval notification email is automatically sent to the target user's email address.

Path Parameters

パラメータ	型	必須	説明
userId	string	必須	User ID

Request Body (optional)

パラメータ	型	必須	説明
reason	string	—	Reason for the approval. If it is not empty, it is recorded in the user information

Request Example

Approve user

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/approve \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{}'

Response Example (200 OK)

JSON

{ "userId": "abc123", "approved": true }

Error Responses

Status	Description
400	User status is not "pending" (cannot approve)
400	reason is not a string, or the body is malformed JSON or not a JSON object (code: "invalid_body")
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	Missing users:manage scope
404	User not found

POST/v1/admin/users/:userId/reject

Revoke a user's approval. Only users with status "approved" can have their approval revoked. After revocation, the status returns to "pending".

note

When revocation succeeds, a notification email is automatically sent to the target user's email address.

Path Parameters

パラメータ	型	必須	説明
userId	string	必須	User ID

Request Example

Reject user

1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/reject \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{}'

Response Example (200 OK)

JSON

{ "userId": "abc123", "status": "pending" }

Error Responses

Status	Description
400	User status is not "approved" (cannot revoke)
403	Missing users:manage scope
404	User not found

Logs SaaS

View audit logs, LLM logs, LLM Gateway logs, access logs, and guardrail alerts. All list endpoints support page-based pagination and date range filters.

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/audit-logs	List audit logs	logs:read
GET	/v1/admin/audit-logs/:id	Get audit log detail	logs:read
GET	/v1/admin/llm-logs	List LLM logs	logs:read
GET	/v1/admin/llm-gateway-logs	List LLM Gateway logs	logs:read
GET	/v1/admin/access-logs	List access logs	logs:read
GET	/v1/admin/access-logs/stats	Get access log stats	logs:read
GET	/v1/admin/guardrail-alerts	List guardrail alerts	logs:read

Common Query Parameters

パラメータ	型	必須	説明
limit	integer	—	Number of items to fetch (1–100, default: 25)
page	integer	—	Page number (1 or more, default: 1)
from	string	—	Start date (an existing date in YYYY-MM-DD format, UTC). A value in another format, a date that does not exist, or a non-string value returns 400
to	string	—	End date (an existing date in YYYY-MM-DD format, UTC). Includes the end of the specified day. A value in another format, a date that does not exist, or a non-string value returns 400

GET/v1/admin/audit-logs

List audit logs. Returned in descending order of creation date.

Request Example

List audit logs

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
auditLogs	array	Array of audit log objects
auditLogs[].auditLogId	string	Audit log ID
auditLogs[].resource	string	Resource operated on (e.g. users/show, config/organizations/create, config/job-types/edit)
auditLogs[].action	string	Operation action (approve / reject / promote / demote / create / update / delete, etc.)
auditLogs[].meta	object | null	Additional metadata
auditLogs[].userId	string	User ID who performed the operation. For operations with a system integration token (Client Credentials flow), client:<client ID>
auditLogs[].userEmail	string | null	Email address of the user
auditLogs[].userName	string | null	Display name of the user. For operations with a system integration token (Client Credentials flow), the client name
auditLogs[].ipAddress	string | null	IP address
auditLogs[].userAgent	string | null	User-Agent
auditLogs[].createdAt	string	Creation date and time (ISO 8601)
total	integer	Total count
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether the next page exists

Example Response (200 OK)

JSON

{
  "auditLogs": [
    {
      "auditLogId": "6b4366a3-791d-4f60-a9ef-24bdb3303e36",
      "resource": "users/list",
      "action": "approve",
      "meta": {
        "userName": "user2@example.com",
        "timestamp": "2026-04-19T13:03:27.238Z",
        "isApproved": true
      },
      "userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "userEmail": "admin@example.com",
      "userName": "admin@example.com",
      "ipAddress": "203.0.113.140",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
      "createdAt": "2026-04-19T13:03:27.479Z"
    },
    {
      "auditLogId": "c14d6065-7c35-44f6-8eea-033ede09bf3a",
      "resource": "users/show",
      "action": "delete",
      "meta": {
        "userName": "user1@example.com",
        "timestamp": "2026-04-19T05:04:19.745Z",
        "userEmail": "user1@example.com"
      },
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "Billing integration",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:04:19.876Z"
    },
    {
      "auditLogId": "f84ef377-9d75-4875-9958-b084c91a3c9b",
      "resource": "organizations",
      "action": "delete",
      "meta": {},
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "Billing integration",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:02:01.736Z"
    }
  ],
  "total": 1537,
  "limit": 3,
  "page": 1,
  "hasMore": true
}

GET/v1/admin/audit-logs/:id

Get a single audit log.

Path Parameters

パラメータ	型	必須	説明
id	string	必須	Audit log ID (auditLogId in the list)

Request Example

Get audit log

1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs/c14d6065-7c35-44f6-8eea-033ede09bf3a \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
auditLogId	string	Audit log ID
resource	string	Resource operated on (e.g. users/show, config/organizations/create, config/job-types/edit)
action	string	Operation action (approve / reject / promote / demote / create / update / delete, etc.)
meta	object | null	Additional metadata
userId	string	User ID who performed the operation. For operations with a system integration token (Client Credentials flow), client:<client ID>
userEmail	string | null	Email address of the user
userName	string | null	Display name of the user. For operations with a system integration token (Client Credentials flow), the client name
ipAddress	string | null	IP address
userAgent	string | null	User-Agent
createdAt	string	Creation date and time (ISO 8601)

Example Response (200 OK)

JSON

{
  "auditLogId": "c14d6065-7c35-44f6-8eea-033ede09bf3a",
  "resource": "users/show",
  "action": "delete",
  "meta": {
    "userName": "user1@example.com",
    "timestamp": "2026-04-19T05:04:19.745Z",
    "userEmail": "user1@example.com"
  },
  "userId": "client:billing-integration",
  "userEmail": "service-account-client@federation.invalid",
  "userName": "Billing integration",
  "ipAddress": "198.51.100.23",
  "userAgent": "Mozilla/5.0 (...)",
  "createdAt": "2026-04-19T05:04:19.876Z"
}

Error Responses

Status	Description
403	logs:read scope is missing
404	The specified audit log is not found

GET/v1/admin/llm-logs

List LLM logs. Returned in descending order of timestamp.

Request Example

List LLM logs

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
llmLogs	array	Array of LLM log objects
llmLogs[].llmLogId	string	LLM log ID
llmLogs[].timestamp	string | null	Timestamp
llmLogs[].service	string | null	Service name
llmLogs[].operation	string | null	Operation name
llmLogs[].durationMs	number | null	Processing time (milliseconds)
llmLogs[].conversationId	string | null	Conversation ID
llmLogs[].intentType	string | null	Intent type
llmLogs[].confidenceScore	number | null	Confidence score
llmLogs[].toolsUsed	number | null	Number of tool calls — not a list of tool names, and not a count of distinct tools (calling the same tool 5 times gives 5). null means not measured; 0 means the run was measured and made no tool call. The two are distinct — do not treat 0 as null.
llmLogs[].success	boolean | null	Success/failure
llmLogs[].agentType	string | null	Agent type
llmLogs[].agentLevel	string | null	Agent level
llmLogs[].taskComplexity	string | null	Task complexity
llmLogs[].currentMessage	string | null	Current message
llmLogs[].contextSummary	string | null	Context summary
llmLogs[].suggestedApproach	string | null	Suggested approach
llmLogs[].conversationGoal	string | null	Conversation goal
llmLogs[].finalContent	string | null	Final output content
llmLogs[].metadata	object | null	Supplementary metadata that varies by operation (keys vary)
llmLogs[].createdAt	string | null	Creation date and time
total	integer	Total count
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether the next page exists

Example Response (200 OK)

JSON

{
  "llmLogs": [
    {
      "llmLogId": "33098",
      "timestamp": "2026-04-19T04:12:51.102Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 5574.6,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": "complex_task",
      "confidenceScore": 0.95,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "Tell me about this URL https://example.com/path",
      "contextSummary": "User is asking about a URL.",
      "suggestedApproach": "execute_single_tool",
      "conversationGoal": "Information about the contents or purpose of the specified URL",
      "finalContent": null,
      "metadata": {
        "message.id": "02038f42-154b-4363-9beb-d31512934ec5",
        "task.complexity": "moderate",
        "detected_language": "en",
        "requires_planning": true
      },
      "createdAt": "2026-04-18T19:16:16.964Z"
    },
    {
      "llmLogId": "33097",
      "timestamp": "2026-04-19T04:12:48.730Z",
      "service": "agent-executor",
      "operation": "agent.guardrail.completed",
      "durationMs": 3170.34,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": null,
      "confidenceScore": null,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent.guardrails",
      "agentLevel": null,
      "taskComplexity": null,
      "currentMessage": null,
      "contextSummary": null,
      "suggestedApproach": null,
      "conversationGoal": null,
      "finalContent": null,
      "metadata": { "guardrail_detected": false },
      "createdAt": "2026-04-18T19:16:14.619Z"
    },
    {
      "llmLogId": "33096",
      "timestamp": "2026-04-19T04:12:33.662Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 4213.47,
      "conversationId": "4d7c798d-2e3e-4d40-86ab-cbb6c685a3fb",
      "intentType": "conversation",
      "confidenceScore": 1,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "Hello",
      "contextSummary": "New conversation. User is greeting.",
      "suggestedApproach": "conversational_response",
      "conversationGoal": "Greeting exchange with the AI assistant",
      "finalContent": null,
      "metadata": {
        "message.id": "cea9dbcc-4723-452a-bdcd-aa5f3a0e9ca6",
        "task.complexity": "simple",
        "detected_language": "en",
        "requires_planning": false
      },
      "createdAt": "2026-04-18T19:15:59.681Z"
    }
  ],
  "total": 33098,
  "limit": 3,
  "page": 1,
  "hasMore": true
}

GET/v1/admin/llm-gateway-logs

List LLM Gateway logs. Returned in descending order of creation time. One request = one row, recording usage such as model, provider, tokens, cost, and latency.

Request Example

List LLM gateway logs

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
llmGatewayLogs	array	Array of LLM Gateway log objects
llmGatewayLogs[].llmGatewayLogId	string	LLM Gateway log ID
llmGatewayLogs[].createdAt	string | null	Creation date and time
llmGatewayLogs[].virtualKeyId	string | null	Virtual key ID (calling client)
llmGatewayLogs[].clientSessionId	string | null	Client session ID
llmGatewayLogs[].clientAgentId	string | null	Client agent ID
llmGatewayLogs[].apiFlavor	string | null	API flavor
llmGatewayLogs[].modelName	string | null	Model name (as requested)
llmGatewayLogs[].resolvedModel	string | null	Resolved model name
llmGatewayLogs[].provider	string | null	Provider
llmGatewayLogs[].deployment	string | null	Deployment
llmGatewayLogs[].tier	string | null	Tier
llmGatewayLogs[].stream	boolean | null	Whether streaming was used
llmGatewayLogs[].success	boolean | null	Success/failure
llmGatewayLogs[].httpStatus	number | null	HTTP status
llmGatewayLogs[].errorType	string | null	Error type
llmGatewayLogs[].errorCode	string | null	Error code
llmGatewayLogs[].usageStatus	string | null	Usage status
llmGatewayLogs[].latencyMs	number | null	Latency (milliseconds)
llmGatewayLogs[].inputTokens	number | null	Input token count
llmGatewayLogs[].outputTokens	number | null	Output token count
llmGatewayLogs[].totalTokens	number | null	Total token count
llmGatewayLogs[].cachedTokens	number | null	Cached token count
llmGatewayLogs[].cacheCreationInputTokens	number | null	Cache creation input token count
llmGatewayLogs[].reasoningTokens	number | null	Reasoning token count
llmGatewayLogs[].costUsd	number | string | null	Cost (USD)
llmGatewayLogs[].currency	string | null	Currency
llmGatewayLogs[].metadata	object | null	Supplementary metadata (keys vary)
total	integer	Total count
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether the next page exists

GET/v1/admin/access-logs

List access logs. Returned in descending order of timestamp.

Request Example

List access logs

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
accessLogs	array	Array of access log objects
accessLogs[].timestamp	string	Timestamp
accessLogs[].sourceNamespace	string | null	Source namespace
accessLogs[].sourceIp	string | null	Source IP address
accessLogs[].method	string | null	HTTP method
accessLogs[].host	string | null	Host name
accessLogs[].path	string | null	Request path
accessLogs[].userAgent	string | null	User-Agent
accessLogs[].statusCode	number | null	HTTP status code
accessLogs[].durationMs	number | null	Processing time (milliseconds)
accessLogs[].authzResult	string | null	Authorization result
accessLogs[].authzReason	string | null	Authorization reason
total	integer	Total count
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether the next page exists
skippedCount	integer	Number of log rows on this page that could not be read (not included in accessLogs; total counts them)

Example Response (200 OK)

JSON

{
  "accessLogs": [
    {
      "timestamp": "2026-04-19T05:17:36.735896",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 1,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:50:36.766451",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "update.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 6,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:45:48.481023",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 0,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    }
  ],
  "total": 57806,
  "limit": 3,
  "page": 1,
  "hasMore": true,
  "skippedCount": 0
}

GET/v1/admin/access-logs/stats

Retrieves access log stats (the number of requests, the numbers allowed and denied, and the paths and hosts denied most often). Specify the period with the common query parameters from and to (both days are included). If omitted, the whole period is used. limit and page are not used.

Request Example

Get access log stats

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs/stats?from=2026-04-01&to=2026-04-15" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
totalRequests	integer	Number of requests in the period (those with a recorded authorization result)
allowedRequests	integer	Number of allowed requests
deniedRequests	integer	Number of denied requests
blockRate	number	Ratio of denied requests (deniedRequests ÷ totalRequests, rounded to 4 decimal places, from 0 to 1; 0 when there are no requests in the period)
topBlockedPaths	array	Request paths denied most often (up to 10, most first)
topBlockedPaths[].path	string | null	Request path. null if it is not recorded in the log
topBlockedPaths[].count	integer	Number of denials
topBlockedHosts	array	Hosts denied most often (up to 10, most first)
topBlockedHosts[].host	string | null	Host name. null if it is not recorded in the log
topBlockedHosts[].count	integer	Number of denials

Response Example (200 OK)

JSON

{
  "totalRequests": 57806,
  "allowedRequests": 57790,
  "deniedRequests": 16,
  "blockRate": 0.0003,
  "topBlockedPaths": [
    { "path": "/upload", "count": 9 },
    { "path": "/", "count": 7 }
  ],
  "topBlockedHosts": [
    { "host": "files.example.com:443", "count": 12 },
    { "host": "api.example.net:443", "count": 4 }
  ]
}

GET/v1/admin/guardrail-alerts

Lists guardrail alerts. Results are returned in descending order of detection time.

These are records where Prompt Shield (prompt injection and jailbreak attempts) or Text Moderation (harmful content) detected a violation and execution was stopped. The detection surface (sourceSurface) is either AI agent execution (agent_executor) or the LLM Gateway (llm_gateway).

Request Example

List guardrail alerts

1curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)

Field	Type	Description
guardrailAlerts	array	Array of guardrail alert objects
guardrailAlerts[].guardrailAlertId	string	Guardrail alert ID
guardrailAlerts[].detectedAt	string	Detection time (ISO 8601 format)
guardrailAlerts[].sourceSurface	string	Detection surface (agent_executor: during AI agent execution / llm_gateway: via LLM Gateway)
guardrailAlerts[].detectionTypes	array	Detection types (jailbreak_attack: prompt injection / harmful_content: harmful content)
guardrailAlerts[].promptShieldOrigin	object | null	Where Prompt Shield detected the attack. Contains user_prompt (the user input) and document_indexes (positions in attached documents). Document contents are not included
guardrailAlerts[].moderationCategories	object | null	Severity per category. Hate / Sexual / SelfHarm / Violence on a four-level scale of 0, 2, 4, and 6
guardrailAlerts[].moderationThreshold	integer | null	Threshold used for the decision
guardrailAlerts[].policyOutcome	string	Policy outcome. Currently only blocked (execution stopped)
guardrailAlerts[].responseTemplateCode	string | null	Code of the canned response returned to the user
guardrailAlerts[].status	string	Triage status (open: not yet handled / escalated: escalated / closed: resolved / false_positive: false detection)
guardrailAlerts[].resolutionCode	string | null	Resolution code
guardrailAlerts[].resolvedAt	string | null	Resolution time (ISO 8601 format)
guardrailAlerts[].resolvedBy	string | null	User ID of the administrator who resolved the alert
guardrailAlerts[].createdAt	string	Creation time (ISO 8601 format)
guardrailAlerts[].updatedAt	string	Update time (ISO 8601 format)
total	integer	Total number of records
limit	integer	Number of items fetched
page	integer	Page number
hasMore	boolean	Whether a next page exists

About the users who triggered detections

This API does not return information that identifies the user who triggered a detection (user ID, conversation ID, or message ID). It is intended for reviewing guardrail quality and tracking the status of safety responses, and cannot be used to trace the behavior of individual users.

In addition, detections of SelfHarm alone are not recorded as alerts.

Response Example (200 OK)

JSON

{
  "guardrailAlerts": [
    {
      "guardrailAlertId": "1f2e3d4c-5b6a-4789-8c9d-0e1f2a3b4c5d",
      "detectedAt": "2026-08-13T02:10:00.000Z",
      "sourceSurface": "agent_executor",
      "detectionTypes": ["harmful_content"],
      "promptShieldOrigin": null,
      "moderationCategories": {
        "Hate": 4,
        "Sexual": 0,
        "SelfHarm": 0,
        "Violence": 0
      },
      "moderationThreshold": 2,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "open",
      "resolutionCode": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "createdAt": "2026-08-13T02:10:00.100Z",
      "updatedAt": "2026-08-13T02:10:00.100Z"
    },
    {
      "guardrailAlertId": "2a3b4c5d-6e7f-4890-9a1b-2c3d4e5f6a7b",
      "detectedAt": "2026-08-12T09:32:11.000Z",
      "sourceSurface": "llm_gateway",
      "detectionTypes": ["jailbreak_attack"],
      "promptShieldOrigin": {
        "user_prompt": true,
        "document_indexes": []
      },
      "moderationCategories": null,
      "moderationThreshold": null,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "closed",
      "resolutionCode": "policy_violation_confirmed",
      "resolvedAt": "2026-08-12T11:05:00.000Z",
      "resolvedBy": "8f14e45f-ceea-4d3c-9b2a-1a2b3c4d5e6f",
      "createdAt": "2026-08-12T09:32:11.050Z",
      "updatedAt": "2026-08-12T11:05:00.000Z"
    }
  ],
  "total": 14,
  "limit": 2,
  "page": 1,
  "hasMore": true
}

Master Data Management SaaS

CRUD operations for organizations and job types. Unlike the read-only master data endpoints (/v1/organizations, /v1/job-types), creation, updates, and deletion require master:manage scope.

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/organizations	List organizations	master:manage
POST	/v1/admin/organizations	Create organization	master:manage
GET	/v1/admin/organizations/:identifier	Get organization detail	master:manage
PATCH	/v1/admin/organizations/:identifier	Update organization	master:manage
DELETE	/v1/admin/organizations/:identifier	Delete organization	master:manage
GET	/v1/admin/job-types	List job types	master:manage
POST	/v1/admin/job-types	Create job type	master:manage
GET	/v1/admin/job-types/:identifier	Get job type detail	master:manage
PATCH	/v1/admin/job-types/:identifier	Update job type	master:manage
DELETE	/v1/admin/job-types/:identifier	Delete job type	master:manage

GET/v1/admin/organizations

List organizations. Fetches all records (no pagination).

Request Example

List organizations (admin)

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

Response Fields (200 OK)

Field	Type	Description
organizations	array	Array of organization objects
organizations[].code	string	Organization code
organizations[].name	string	Organization name
organizations[].displayOrder	integer	Display order
organizations[].isActive	boolean	Enabled/disabled
organizations[].createdAt	string	Creation date and time
organizations[].updatedAt	string	Last updated date and time

Example Response (200 OK)

JSON

{
  "organizations": [
    {
      "code": "sample_org",
      "name": "Sample Organization",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "2025-12-12T10:40:45.220Z",
      "updatedAt": "2026-04-13T01:21:57.695Z"
    },
    {
      "code": "sales",
      "name": "Sales Division",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "engineering",
      "name": "Engineering Division",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "Other",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ]
}

Error Responses

Status	Description
403	master:manage scope is missing

POST/v1/admin/organizations

Create an organization.

Request Body

パラメータ	型	必須	説明
code	string	必須	Organization code (unique)
name	string	必須	Organization name
displayOrder	integer	—	Display order. If omitted, the item is appended to the end of existing items
isActive	boolean	—	Enabled/disabled (default: true)

Example Response (201 Created)

JSON

{
  "code": "marketing",
  "name": "Marketing Division",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:15:32.000Z",
  "updatedAt": "2026-04-19T02:15:32.000Z"
}

Error Responses

Status	Description
400	Invalid request body (missing code / name, code or name is not a string, isActive is not a boolean, displayOrder is not an integer, the body is malformed JSON or not a JSON object (code: "invalid_body"), etc.)
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	master:manage scope is missing
409	An organization with the same code already exists

GET/v1/admin/organizations/:identifier

Get organization detail. Can be specified by UUID or organization code.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Organization UUID or organization code

Request Example

Get organization

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

Example Response (200 OK)

JSON

{
  "code": "sales",
  "name": "Sales Division",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}

Error Responses

Status	Description
403	master:manage scope is missing
404	The specified organization is not found

PATCH/v1/admin/organizations/:identifier

Update an organization. Only name and isActive can be updated.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Organization UUID or organization code

Request Body

パラメータ	型	必須	説明
name	string	—	Organization name
isActive	boolean	—	Enabled/disabled

Example Response (200 OK)

JSON

{
  "code": "sales",
  "name": "Sales Division",
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:18:40.000Z"
}

Error Responses

Status	Description
400	Invalid request body (name exceeds 255 characters, neither name nor isActive provided, name is not a string or isActive is not a boolean, the body is malformed JSON or not a JSON object (code: "invalid_body"), etc.). Fields other than name / isActive are ignored
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	master:manage scope is missing
404	The specified organization was not found

DELETE/v1/admin/organizations/:identifier

Delete an organization.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Organization UUID or organization code

Request Example

Delete organization

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

Response Example (200 OK)

JSON

{ "code": "sales", "deleted": true }

Field	Type	Description
code	string	The deleted organization code (returns the path parameter identifier as-is)
deleted	boolean	Always true

Error Responses

Status	Description
403	master:manage scope is missing
404	The specified organization was not found

GET/v1/admin/job-types

List job types. Fetches all records (no pagination). Response fields have the same structure as the organizations list (organizations → jobTypes, organization code → job type code).

Response Fields (200 OK)

Field	Type	Description
jobTypes	array	Array of job type objects
jobTypes[].code	string	Job type code
jobTypes[].name	string	Job type name
jobTypes[].displayOrder	integer	Display order
jobTypes[].isActive	boolean	Enabled/disabled
jobTypes[].createdAt	string	Creation date and time
jobTypes[].updatedAt	string	Last updated date and time

Example Response (200 OK)

JSON

{
  "jobTypes": [
    {
      "code": "engineer",
      "name": "Engineer",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "sales",
      "name": "Sales",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "Other",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ]
}

Error Responses

Status	Description
403	master:manage scope is missing

POST/v1/admin/job-types

Create a job type. The request body has the same structure as organization creation.

Example Response (201 Created)

JSON

{
  "code": "manager",
  "name": "Manager",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:20:15.000Z",
  "updatedAt": "2026-04-19T02:20:15.000Z"
}

Error Responses

Status	Description
400	Invalid request body (missing code / name, code or name is not a string, isActive is not a boolean, displayOrder is not an integer, the body is malformed JSON or not a JSON object (code: "invalid_body"), etc.)
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	master:manage scope is missing
409	A job type with the same code already exists

GET/v1/admin/job-types/:identifier

Get job type detail. Can be specified by UUID or job type code.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Job type UUID or job type code

Request Example

Get job type

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

Example Response (200 OK)

JSON

{
  "code": "engineer",
  "name": "Engineer",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}

Error Responses

Status	Description
403	master:manage scope is missing
404	Job type not found

PATCH/v1/admin/job-types/:identifier

Update a job type. Only name and isActive can be updated.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Job type UUID or job type code

Request Body

パラメータ	型	必須	説明
name	string	—	Job type name
isActive	boolean	—	Active/Inactive

Request Example

Update job type

1curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{"name": "Senior Engineer", "isActive": true}'

Example Response (200 OK)

JSON

{
  "code": "engineer",
  "name": "Senior Engineer",
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:22:55.000Z"
}

Error Responses

Status	Description
400	Invalid request body (name exceeds 255 characters, neither name nor isActive provided, name is not a string or isActive is not a boolean, the body is malformed JSON or not a JSON object (code: "invalid_body"), etc.). Fields other than name / isActive are ignored
415	The body Content-Type is not application/json (code: "unsupported_media_type")
403	master:manage scope is missing
404	The specified job type was not found

DELETE/v1/admin/job-types/:identifier

Delete a job type. The response structure is the same as organization deletion.

Path Parameters

パラメータ	型	必須	説明
identifier	string	必須	Job type UUID or job type code

Request Example

Delete job type

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

Example Response (200 OK)

JSON

{ "code": "engineer", "deleted": true }

Error Responses

Status	Description
403	master:manage scope is missing
404	The specified job type was not found

Projects SaaS

This section covers calls made with a system integration token (Client Credentials flow). For calls made with an application token (Authorization Code flow), see User API Reference (Projects).

A project is the unit in which multiple agents are placed to carry out work. From an external system you can list projects, start a run, and check run status.

There are two project types, and each is triggered differently.

Type	Description	How runs are triggered
workflow	Advances through steps in order. A run starts from the first enabled step.	POST /v1/projects/{projectId}/runs
cycle	Keeps multiple agents running on their own schedules. An external event can add one extra ad-hoc run.	POST /v1/projects/{projectId}/triggers/{triggerId}/fire

What you can operate on

The projects you can operate on are limited to the project restriction configured in Console (Console Guide — Configuring project restrictions). Specifying a project ID outside that range returns the same 404 Not Found as a project that does not exist. A system integration token can call only the four project API endpoints listed here. Calling any other project API returns 403 Forbidden (forbidden).

Endpoints

メソッド	エンドポイント	説明	Scope (SaaS)
GET	/v1/projects	List projects	project:read
POST	/v1/projects/{projectId}/runs	Start a project run	project:run
POST	/v1/projects/{projectId}/triggers/{triggerId}/fire	Fire a trigger for one ad-hoc run	project:run
GET	/v1/projects/{projectId}/runs/{runId}	Get run status	project:read

GET/v1/projects

Retrieves the list of projects you can access. Supports cursor-based pagination. cycle projects also appear in the list, but they are not valid targets for starting a run (POST /v1/projects/{projectId}/runs).

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)

Any other query parameter is ignored. myRole can only be used with a user token, so it is ignored if specified.

Response Fields (200 OK)

Field	Type	Description
projects	array	Array of project objects
projects[].projectId	string	Project ID (UUID)
projects[].name	string	Project name
projects[].type	string	"workflow" or "cycle"
projects[].status	string	Project state. One of "active", "paused" or "archived"
projects[].tags	array	Array of tags. An empty array when none are set
hasMore	boolean	Whether a next page exists
cursor	string	Cursor for the next page. Included only when hasMore is true

Response Example

JSON

{
  "projects": [
    {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Order processing flow",
      "type": "workflow",
      "status": "active",
      "tags": []
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Always-on inquiry handling",
      "type": "cycle",
      "status": "active",
      "tags": []
    }
  ],
  "hasMore": false
}

Error Responses

Status	Description
400	limit is outside 1-100 or cursor is invalid (code is invalid_parameter)
403	The project:read scope is missing, or the project restriction is missing or invalid (code is insufficient_scope or invalid_project_grant)

POST/v1/projects/{projectId}/runs

Starts a run of a workflow project. Calling it for a cycle project returns 409 Conflict (unsupported_project_type).

Request Headers

Header	Required	Description
Idempotency-Key	Required	A duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and _ . : - only

Path Parameters

パラメータ	型	必須	説明
projectId	string	必須	Project ID (UUID)

Request Body

No body is required. If you send one, make it a JSON object. Any fields it contains are ignored.

Response Fields (201 Created / 200 OK)

Field	Type	Description
runId	string	Run ID (UUID). Use it to retrieve run status
existing	boolean?	true when an existing run was returned for a resend with the same Idempotency-Key. Not included on the first call

The first call returns 201 Created; a resend with the same Idempotency-Key returns 200 OK.

Request Example

curl

curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: nightly-batch-20260917" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Example

JSON

{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

How Idempotency-Key is handled

• Keys are matched per project. They do not expire.
• Resending with the same key returns the same run even after the project has been paused, after the concurrent-run limit has been reached, or after that run has finished.
• If a timeout leaves the outcome unknown, simply resend with the same key. Nothing is run twice.
• To start a different run, always issue a new key.

Error Responses

Status	code	Description
400	idempotency_key_required	The Idempotency-Key header is missing
400	idempotency_key_invalid	The Idempotency-Key length or character set is invalid
400	invalid_parameter	projectId is not a UUID
400	invalid_body	The request body is malformed JSON or is not a JSON object
413	body_too_large	The request body exceeds 16 KiB
415	unsupported_media_type	A request body is sent with a Content-Type other than application/json
403	insufficient_scope	The project:run scope is missing
403	invalid_project_grant	The project restriction is missing or invalid
404	project_not_found	The project does not exist or is not accessible
400	approvers_required	An enabled review step has no reviewers configured
409	unsupported_project_type	A cycle project was specified
409	project_inactive	The project is not active (paused or archived)
409	unsupported_runtime	The project cannot run in this configuration, for example because agent runtimes are mixed
429	too_many_active_runs	The project already has the maximum number of runs (3 in total) that are running or awaiting review

POST/v1/projects/{projectId}/triggers/{triggerId}/fire

Fires a webhook trigger configured on a cycle project and runs the target agent once, as an extra ad-hoc run. Calling it for a workflow project returns 404 Not Found.

The scheduled runs stay exactly as configured. A fired run is added separately from the schedule. Where an earlier fire has not started running yet, however, a later fire may be merged into that run. Where it is, jobId returns the same value as the earlier fire, so the number of fires and the number of runs do not necessarily match.

Path Parameters

パラメータ	型	必須	説明
projectId	string	必須	Project ID (UUID)
triggerId	string	必須	ID of the trigger to fire (UUID)

Request Body

パラメータ	型	必須	説明
eventId	string	必須	A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and _ . : @ + - only
payload	any	—	Arbitrary JSON passed to the agent. It is serialized to a JSON string and added to the request sent to the agent; anything beyond 8,000 characters after serialization is omitted

Response Fields (202 Accepted)

Field	Type	Description
result	string	"accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)
jobId	string	ID of the receiving job. It cannot be used to get run status (GET /v1/projects/{projectId}/runs/{runId})

Response Example

JSON

{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}

What 202 means here

This 202 Accepted means only that the request was recorded as accepted. The run happens afterwards, and its outcome is not part of this response. Do not treat 202 as business success.

Resending

Idempotency is decided by the combination of project, trigger, and eventId. Resending the same content returns 202 with result: "duplicate". Sending the same eventId with a different payload returns 409 Conflict (event_conflict).

Error Responses

Status	code	Description
400	invalid_event_id	eventId is missing or has an invalid format
400	invalid_parameter	projectId or triggerId is not a UUID
400	invalid_body	The request body is malformed JSON or is not a JSON object
415	unsupported_media_type	A request body is sent with a Content-Type other than application/json
403	insufficient_scope	The project:run scope is missing
403	invalid_project_grant	The project restriction is missing or invalid
404	trigger_not_found	The project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified
409	trigger_disabled	The trigger is disabled
409	project_not_active	The project is not in a runnable state
409	placement_unavailable	The target agent placement does not exist, or no execution principal is configured
409	event_conflict	The same eventId was sent with a different payload
413	body_too_large	The request body exceeds 16 KiB

GET/v1/projects/{projectId}/runs/{runId}

Retrieves the status of a run. Besides runs started through the API (POST /v1/projects/{projectId}/runs), runs started from the UI, by email, or on a schedule can also be retrieved. cycle projects do not create runs, so they are out of scope for this endpoint.

Path Parameters

パラメータ	型	必須	説明
projectId	string	必須	Project ID (UUID)
runId	string	必須	Run ID (UUID)

Response Fields (200 OK)

Field	Type	Description
runId	string	Run ID (UUID)
status	string	Run state. One of "running" (running), "waiting_gate" (awaiting review), "closed_done" (completed), "closed_rejected" (ended by rejection), "closed_failed" (ended by failure) or "cancelled" (cancelled). Any value other than "running" and "waiting_gate" means the run has ended
originType	string | null	How the run started. One of "manual" (started from the UI), "api" (started through the API), "mail" (started by email) or "cron" (scheduled)
originRef	string | null	A reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it
currentStepId	string | null	ID (UUID) of the step in progress. While the run proceeds in separate lanes, the ID of the step before the branch. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain
startedByRef	string | null	Who or what started the run. See the "Who started the run" table below
actorLabel	string | null	Display name of a starter that is not a user (the system integration name or the sender address of an email). null otherwise
startedAt	string | null	Start time (ISO 8601). null before it starts
endedAt	string | null	End time (ISO 8601). null before it ends
summary	string | null	For a completed run, the output of the last completed step that recorded an output (first 2,000 characters). null if there is no such step and for a run that has not completed
runtimeKind	string | null	Kind of runtime ("autonomous"). May be null for older runs
cancelRequestedAt	string | null	Time (ISO 8601) when cancellation was requested. null if not requested
configRevision	number | null	Revision of the case configuration (Marketplace edition runs only). null for SaaS runs
steps	array	Records of the step runs, in the order they were recorded
steps[].runStepId	string	ID of the step run (starts with "rs:")
steps[].stepId	string | null	Step ID (UUID)
steps[].placementId	string | null	ID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)
steps[].executionId	string | null	ID of the agent execution. Set once the agent starts running
steps[].conversationId	string | null	ID of the conversation of the agent execution. Set once the agent starts running
steps[].status	string	One of "pending" (waiting to run), "running" (running), "waiting_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)
steps[].attempt	number | null	Retry count within the same visit (starting at 1)
steps[].lane	string | null	ID of the lane the step belongs to. "main" for steps that are not in a separate lane
steps[].scheduledAt	string | null	When the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts
steps[].startedAt	string | null	Start time (ISO 8601)
steps[].endedAt	string | null	End time (ISO 8601)
steps[].outputSummary	string | null	Summary of the step output
steps[].outcome	string | null	Result of the agent execution. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result
steps[].reasonCode	string | null	Reason code for the result
steps[].held	boolean	Whether the step is held because the project is paused and is waiting to resume
steps[].visit	number | null	Which visit to this step this is (increases with send-backs). null for rows without this record
steps[].reworkReason	string | null	Reason for the send-back
steps[].gateFor	string | null	For a review row, the step run (runStepId) it was raised for
steps[].routedFrom	string | null	When steps were skipped by choosing a destination, the step run (runStepId) that chose it
steps[].late	string | null	Why a result that arrived late was not used to advance the run
steps[].gate	object | null	Summary of a review step. null for rows that are not review steps
steps[].gate.decision	string | null	One of "proceed", "send_back" or "reject". null if not decided yet
steps[].gate.waitSource	string | null	What the review waits for. "human" (a person's decision) or "external" (an external condition)
plannedPlacements	array	Order of steps and placements planned to run, based on the configuration when the run started
plannedPlacements[].stepId	string | null	Step ID (UUID)
plannedPlacements[].placementId	string | null	Placement ID (UUID). null for review steps and steps without an agent
lanes	array	Status of each lane after the branch. An empty array before the branch and for runs that do not use lanes
lanes[].laneId	string	Lane ID
lanes[].name	string | null	Lane name
lanes[].position	number | null	Lane order (starting at 1)
lanes[].state	string	One of "running" (running), "waiting_gate" (awaiting review), "arrived" (waiting to join) or "closed" (ended)
lanes[].currentStepId	string | null	ID (UUID) of the step in progress in that lane. null for a lane waiting to join. For a lane that has ended, the ID of its last step may remain
lanes[].arrived	boolean	Whether the lane has reached the join point

The fields are the same regardless of the token used for the call (an application or a system integration).

Who started the run

Started by	startedByRef	actorLabel
A user (from the UI, through the API, or by email sent from a member address)	User ID	null
A system integration	"client:" followed by the Client ID of the system integration. "system:federation-api" if the Client ID is unknown	Name of the system integration (null if unknown)
Email sent from an address that is not a member	"mail:" followed by a hash of the sender	Sender address
A schedule	null	null

For runs started by a system integration before 2026-09-25, startedByRef is null.

Response Example

JSON

{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}

Error Responses

Status	code	Description
400	invalid_parameter	projectId or runId is not a UUID
403	insufficient_scope	The project:read scope is missing
403	invalid_project_grant	The project restriction is missing or invalid
404	run_not_found	The run does not exist, belongs to another project, or is not accessible

Notes on the Project API

Item	Detail
What 404 means	The same 404 Not Found is returned whether the project does not exist or is not accessible, and the response does not reveal which of the two applies. The code is fixed per endpoint: project_not_found for starting a run, trigger_not_found for firing a trigger, and run_not_found for run status.
When the type is out of scope	Calling trigger fire on a workflow project, or run status on a cycle project, returns 404. Starting a run on a cycle project is the one exception: it returns 409 unsupported_project_type.
Request body	When you send a body to start a run or fire a trigger, make it a JSON object. Anything other than Content-Type: application/json returns 415, malformed JSON or a body that is not a JSON object returns 400 (invalid_body), and a body larger than 16 KiB returns 413.
Unknown fields / queries	Fields and query parameters that are not in the specification are ignored. An invalid value for a documented query parameter, or a cursor that cannot be read, returns 400 Bad Request.
Timeouts	504 Gateway Timeout does not mean "it did not run". Resend a run start with the same Idempotency-Key, and a trigger fire with the same eventId and the same body.

Error Responses

HTTP Status Codes

HTTP status codes that may be returned by any endpoint.

Status	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Invalid or missing token
403 Forbidden	Insufficient permissions to access the resource
404 Not Found	Resource not found
409 Conflict	Resource conflict (e.g., duplicate code)
413 Payload Too Large	Request body exceeds the size limit
415 Unsupported Media Type	The request body format (Content-Type) is not supported
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Internal server error
502 Bad Gateway	Communication error with an upstream service
503 Service Unavailable	Service temporarily unavailable
504 Gateway Timeout	Upstream service response timeout

Error Response Format

All error responses are returned with the following common structure.

Field	Type	Description
error.type	string	Error category. One of "invalid_request_error", "authentication_error", "insufficient_scope_error", "forbidden_error", "not_found_error", "conflict_error", "payload_too_large_error", "rate_limit_error", "server_error", or "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 name that caused the error. Included only for validation errors
error.suggested_action	string	Recommended action to resolve the error. 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"
  }
}

Automatically Recorded Management Operations SaaS

The following management operations automatically generate an audit log entry.

Resource	Operation	action
User	Change role (promote to admin)	promote
User	Change role (demote to general)	demote
User	Approve	approve
User	Revoke approval	reject
User	Delete	delete
Organization	Create	create
Organization	Update	update
Organization	Delete	delete
Job type	Create	create
Job type	Update	update
Job type	Delete	delete