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.
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.
The APIs on this page handle requests as follows. See each endpoint's description and error responses for endpoint-specific handling.
What you sent
How it is handled
Query parameters and body fields not in the specification
Ignored. However, even items not listed on this page may return 400 Bad Request if their type or value is wrong, when the service accepts them
An invalid value for a query parameter in the specification
400 Bad Request
An invalid URL encoding in a path parameter value (a % sequence)
400 Bad Request (invalid_parameter)
A malformed JSON body
400 Bad Request (invalid_body)
A body other than Content-Type: application/json, or a body with an unsupported character set (charset), sent to an endpoint that accepts a JSON body
415 Unsupported Media Type (unsupported_media_type)
A body field of the wrong type
400 Bad Request
If reading the body results in 400 (malformed JSON and so on) or 413 (the size limit was exceeded and so on), that is returned before 415.
Responses carry an x-request-id header. The service assigns this value; a value you send in the request is not used. Please tell us this value when you contact us.
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.
Endpoints using this scheme: the users list and the log lists (audit logs, operation audit logs, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs, and guardrail alerts).
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.
{ "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 } ] }
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.
Status ("unverified", "pending", "approved", or "suspended"). "suspended" is an approved user whose use was suspended in the admin console (cannot sign in)
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
users[].idpSynced
boolean
Whether the user is synced from the identity provider (IdP). For a user with true, an organization or job type that is already set cannot be changed with PUT /v1/admin/users/:userId/affiliation (409 affiliation_managed_by_idp)
Get the list of passkeys registered by a user. Requires either the users:read or users:manage scope. Passkeys are deleted in the admin console (this API cannot delete them).
Creates one user. Requires the users:manage scope. The created user is approved (status is "approved") and counts toward the contracted number of users.
If you do not send password, a temporary password is generated and returned once, as temporaryPassword, in the response to the creation. It cannot be read later, so pass it on to the user. This response has Cache-Control: no-store.
The notification email (sendNotificationEmail) does not contain the password.
Creating users with the same email address at the same time, or creating users at the same time when one more user is left within the contracted number, can give 500 or create users beyond the limit. Create users one after another.
Email address. Leading and trailing whitespace is removed and it is lowercased (up to 255 characters)
displayName
string
必須
Display name (up to 255 characters). Leading and trailing whitespace is removed, and < and > are removed
role
string
必須
"admin" or "user"
organization
string
必須
Organization code (a value from GET /v1/organizations)
job
string
必須
Job type code (a value from GET /v1/job-types)
bio
string
—
Bio (up to 255 characters). Leading and trailing whitespace is removed, and < and > are removed
password
string
—
The first password. 400 if it does not meet the password rules. If omitted, a temporary password is generated and returned in temporaryPassword of the response
temporary
boolean
—
Whether the user must change the password at the first sign-in. If omitted, true when password is not sent, and false when it is sent
sendNotificationEmail
boolean
—
Whether to notify the user of the creation by email. If omitted, true. In an environment that cannot send email, it is not sent and emailSent in the response is false
email, displayName, role, organization, or job is missing; any of them or bio is not a string, empty, or only whitespace (for displayName, organization, job, and bio, also a value that is only whitespace after < and > are removed); role is not "admin" or "user"; displayName or bio is longer than 255 characters; password is empty or only whitespace; temporary or sendNotificationEmail is not a boolean; the email address is malformed; an organization or job type code is wrong; or the password does not meet the rules (code: "invalid_parameter")
400
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")
401
The token is invalid or missing (code: "invalid_token")
A user with the same email address exists (code: "user_exists"; param is email). Use a different email address
409
The contracted number of users has been reached (code: "conflict")
429
The limit on requests per source IP address (30 per hour) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500, 502, 504
The user may have been created. Check with GET /v1/admin/users?search=<email> before sending again (if it was created, sending again gives 409 user_exists). If it was created and you did not receive the temporary password, the user sets one from "Forgot password?" on the sign-in screen. In an environment that cannot send email, set the password again in the admin console
503
The contracted number of users cannot be checked. Wait a moment and send it again
DELETE/v1/admin/users/:userId
Delete a user. A deleted user disappears from the admin console, the chat screens and the API, and this cannot be undone. To have the user's archived conversations, per-conversation work notes and per-user settings records deleted as well, see the administrator guide. Requires users:manage scope. Access tokens issued to the user before the deletion may remain usable until they expire (the expires_in returned when they were obtained).
The specified user was not found (including already deleted)
429
The limit on requests per source IP address (10 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
Some of the user's data could not be deleted, so the deletion was stopped (code: "user_delete_incomplete"). The user is kept. Delete it again
PUT/v1/admin/users/:userId/role
Change a user's role. Only users with status "approved", and "suspended" users whose emailVerified is true, can have their role changed.
Behavior on Role Change
When demoting to user: The target user's existing sessions are not ended automatically. The permissions in access tokens that were already issued do not change until they expire.
When promoting to admin: The target user's existing sessions continue, and the new permissions take effect in tokens issued after the promotion.
role is missing or invalid, the body is malformed JSON (code: "invalid_body"), or the target user is neither "approved" nor a "suspended" user whose emailVerified is true
415
The body Content-Type is not application/json (code: "unsupported_media_type")
403
users:manage scope is missing
404
User not found
409
Another update of the same user (approval, role change, profile update, and so on) is in progress (code: "conflict"). Wait a moment and send it again
429
The limit on requests per source IP address (100 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
The role change could not be finished (code: "internal_error"). Get the user again to check the current role, and send the same change again if needed
POST/v1/admin/users/:userId/approve
Approve a user. Only users with status "pending" can be approved. A user whose approval was revoked (stopped) is also shown as "pending" and can be approved; approving lets the user sign in again and the data is still there, but what the revocation stopped (running conversations, personal schedules, and the patrols and runs of projects the user owns) and the deleted connections to external services are not restored automatically.
note
When approval succeeds, an approval notification email is automatically sent to the target user's email address.
User status is not "pending" (cannot approve: the email address has not been verified, or the user is already approved, including suspended users)
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
429
The limit on requests per source IP address (10 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
409
After you got the user, it was approved by another operation, the contracted number of users was reached, or another update of the same user is in progress (code: "conflict")
500
The approval was not applied, because the change could not be passed to the chat; the user is not approved yet (code: "user_suspension_incomplete"). Send the same request again; it can be repeated
POST/v1/admin/users/:userId/reject
Revoke a user's approval. Only users with status "approved", and "suspended" users whose emailVerified is true, can have their approval revoked (a user whose approval was already revoked can be revoked again; it is a retry). Revoking disables the user, who can no longer sign in, and removes the user from the contracted number of accounts. Conversations, files, schedules and other data are kept. Revoking stops the same things as suspending (/suspend): running conversations and personal schedules, the patrols and open runs of projects the user owns, and the user's connections to external services are deleted. Approving the user again (approve) does not restore them automatically. Suspending (/suspend) keeps the user counted in the number of accounts; revoking removes the user from it. After revocation, the status is shown as "pending". Access tokens issued to the user before the revocation may remain usable until they expire (the expires_in returned when they were obtained).
note
A notification email is automatically sent to the target user's email address once, when an approved user is revoked.
The user is neither "approved" nor a "suspended" user whose emailVerified is true (cannot revoke). A user whose approval was already revoked can be revoked again (a retry; no email is sent)
403
Missing users:manage scope
404
User not found
429
The limit on requests per source IP address (10 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
409
Another update of the same user is in progress (code: "conflict")
500
The approval is revoked, but the stop of use could not be passed to the chat (code: "user_suspension_incomplete"). The user stays disabled and unapproved. Send the same request again to retry the stop
POST/v1/admin/users/:userId/suspend
Suspend a user. The approval status and data are kept, and the status in the list becomes "suspended". A suspended user cannot sign in. It also tries to end the user's signed-in sessions (if they cannot be ended, the suspension still succeeds, and sending the same request again tries again). Suspending also stops the user's running conversations and personal scheduled runs, deletes the user's own connections to external services (project connections are kept), and stops the sweeps and open workflow runs of the projects the user owns (the project definitions are kept). Resuming the user does not restore what was stopped. In a project owned by a suspended user, starting a workflow run and resuming a closed run are refused with 409 Conflict (principal_suspended). Only approved users can be suspended. Sending the same operation again gives the same result. A token issued through the tenant cannot suspend the user of its own idp.sub (409).
The user cannot be suspended (not approved, deleted, or permanently locked), the token tried to suspend the user of its own idp.sub, or another update of the same user is in progress (code: "conflict"). The error message and its guidance tell which one applies
429
The limit on requests per source IP address (10 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
The suspension was not fully applied (sign-in was stopped, but the change did not reach chat) (code: "user_suspension_incomplete"). Send the same request again
500
Another error (code: "internal_error"). Send the same request again
POST/v1/admin/users/:userId/resume
Resume a suspended user. Sending the same operation again gives the same result.
The user cannot be resumed (not approved, deleted, or permanently locked), or another update of the same user is in progress (code: "conflict"). The error message and its guidance tell which one applies
429
The limit on requests per source IP address (10 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
Resuming was not fully applied, and the user is still suspended (code: "user_suspension_incomplete"). Send the same request again
500
Another error. This is also returned when chat was resumed but sign-in could not be resumed (code: "internal_error"). Send the same request again
POST/v1/admin/users/:userId/unlock
Unlock a user who was locked out by failed sign-ins. If the user was not locked, nothing changes and wasLocked is false.
Another update of the same user is in progress (code: "conflict"). Wait a moment and send it again
429
The limit on requests per source IP address (100 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
The unlock could not be finished (code: "internal_error"). Send the same request again
PUT/v1/admin/users/:userId/affiliation
Change a user's affiliation (organization code) and job (job type code). Both are required. Look up the codes with GET /v1/organizations and GET /v1/job-types. The response has the values before and after the change (null for a previous value that was not set). Changing the affiliation removes the user's organization admin role and organization operations role in organizations other than the new one (the auditor role is kept). After a 500, the affiliation and job may already have changed. Sending the same request again redoes the cleanup of organization roles. For a user synced from the identity provider (IdP) (users[].idpSynced is true in GET /v1/admin/users), an organization or job type that is already set cannot be changed (409 affiliation_managed_by_idp). Change the organization and job type in the identity provider (IdP) that syncs this user. To fill in a value that is not set yet, send the current value for the one that is already set (users[].organization.value and users[].jobType.value in GET /v1/admin/users). An invalid code returns 400 before this check.
Another update of the same user is in progress (code: "conflict"). Wait a moment and send it again
409
The organization and job type of this user are synced from the identity provider (IdP) and cannot be changed (code: "affiliation_managed_by_idp"). Change the organization and job type in the identity provider (IdP) that syncs this user. To fill in a value that is not set yet, send the current value for the one that is already set
429
The limit on requests per source IP address (100 per minute) was exceeded (code: "rate_limit_exceeded"). Wait a moment and send it again
500
The change of affiliation and job could not be finished (code: "internal_error"). The affiliation and job may already have changed. Sending the same request again redoes the cleanup of organization roles
View audit logs, operation audit logs, user action audit, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs (records of outbound communication that was allowed or blocked), and guardrail alerts. The user action audit list uses cursor-based pagination and the other lists use page-based pagination. All lists support date range filters.
Number of items to fetch (1–100, default: 25. For the user action audit, default: 50)
page
integer
—
Page number (1 or more, default: 1). Not used for the user action audit (use cursor)
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
order
string
—
Sort order: "asc" or "desc" (default: "desc"), by the time column of each log. Other values return 400. Access logs and the user action audit are always newest first, and order is ignored
GET/v1/admin/audit-logs
List audit logs. By default, returned in descending order of creation date (use order for ascending).
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 / reset-password, etc.). For records whose meta has an action, that value (same as shown in the admin console)
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
List the user action audit: records of actions users performed in the chat (opening, creating or deleting conversations, files, shares and so on). Always newest first, with cursor-based pagination (limit is 1–100, default 50). Message content is not recorded. The “Metadata” shown on the screen (fingerprinted IP addresses and user agents, and so on) is not returned.
Without a period (from and to), the last 30 days are returned. Without from only, the 30 days up to the to date; without to only, up to now. A from later than to returns 400.
From the second page on, send the same user_id and action as the first page together with cursor. Changing the conditions changes the range and can cause duplicate or missing items. The period of the first page is kept in cursor, so from and to sent with later pages do not change it.
Even when fewer items than limit are returned, there are more while hasMore is true.
Exact match on the ID of the user who acted (userId), up to 128 characters
action
string
—
Exact match on the action (action), up to 64 characters
An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, a value that is too long, or a parameter given twice or more returns 400.
For the second page, send the cursor from the first response with the same filters (action in this example).
curl
curl"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&action=export&cursor=<cursor from the previous response>"\ -H"Authorization: Bearer <access_token>"
limit is not 1–100; from or to is not an existing date in YYYY-MM-DD format; from is later than to; user_id or action is only whitespace, has leading or trailing whitespace, is too long, or is given twice or more; or cursor is invalid (not a value from a previous response) (code: "invalid_parameter")
400
The service did not accept the period (e.g. to is omitted and from is a date after today) (code: "bad_request")
List operation audit logs: what users, agents and the system carried out, such as agents' tool calls, allows and denies by execution rules, and approvals. By default, returned in descending order of occurrence time (use order for ascending). The text itself is not recorded. The “Integrity Hash of Record Content”, “Row Hash” and “Metadata” shown on the screen are not returned.
Exact match on the event type (eventType), e.g. "tool.invoked", "approval.resolved", "gate.resolved", "run.started", "agent.copied"
decision
string
—
Exact match on the decision (decision), e.g. "allow", "deny", "completed", "failed", "copied"
source
string
—
Exact match on the source (source), e.g. "worker", "cli-api", "front", "admin", "login", "agent_executor"
actor_type
string
—
Exact match on the actor type (actorType), e.g. "human", "agent", "system"
actor_kind
string
—
Exact match on the actor kind (actorKind), e.g. "human", "human_external", "system", "agent", "unknown"
actor_ref
string
—
Exact match on the actor (actorRef)
conversation_id
string
—
Exact match on the conversation ID (conversationId)
execution_id
string
—
Exact match on the execution ID (executionId)
root_execution_id
string
—
Exact match on the execution series ID (rootExecutionId)
project_id
string
—
Exact match on the project ID (projectId). A value that is not a UUID returns 400
request_id
string
—
Exact match on the request ID (requestId)
Values are not restricted, and an unknown value matches nothing. An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, or a parameter given twice or more returns 400.
limit, page, from, to, or order is invalid; a filter value is only whitespace, has leading or trailing whitespace, or is given twice or more; or project_id is not a UUID (code: "invalid_parameter")
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":[ { "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. By default, returned in descending order of creation time (use order for ascending). One request = one row, recording usage such as model, provider, tokens, cost, and latency.
List the LLM Gateway operation audit: a record of operations performed through the LLM Gateway. There are no records if you do not use the LLM Gateway. By default, returned in descending order of occurrence time (use order for ascending). The “Request ID”, “Detail Digest”, “Row Hash” and “Metadata” shown on the screen are not returned.
Exact match on the event type (eventType), e.g. "auth.denied", "guardrail.blocked", "policy.pii_blocked", "policy.mcp_stripped", "limit.rpm_exceeded", "limit.budget_exceeded"
decision
string
—
Exact match on the decision (decision), e.g. "allowed", "denied", "blocked", "degraded", "stripped", "throttled"
api_flavor
string
—
Exact match on the API flavor (apiFlavor), e.g. "chat", "responses", "messages", "embeddings"
virtual_key_id
string
—
Exact match on the virtual key ID (virtualKeyId)
Values are not restricted, and an unknown value matches nothing. An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, or a parameter given twice or more returns 400.
limit, page, from, to, or order is invalid; or a filter value is only whitespace, has leading or trailing whitespace, or is given twice or more (code: "invalid_parameter")
List access logs. Access logs are records of outbound communication that was allowed or blocked. Returned in descending order of timestamp (order cannot be specified).
Detection type (a value in detectionTypes, for example "jailbreak_attack" or "harmful_content")
moderation_category
string
—
Harmful content category (a key in moderationCategories, for example "Hate", "Violence", or "Sexual")
shield_origin
string
—
"userPrompt" / "documents" / "both" / "unknown"
policy_category
string
—
Attack method category (a value of policyCategory)
A value other than those above for status, source_surface, resolution_code, or shield_origin returns 400. detection_type, moderation_category, and policy_category accept any value, and an unknown value matches nothing.
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).
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[].policyCategory
string | null
Attack method category (for example prompt_injection, system_prompt_extraction, or credential_request). null for a detection without this category
guardrailAlerts[].responseTemplateCode
string | null
Code of the canned response returned to the user
guardrailAlerts[].status
string
Triage status (open: not yet handled / investigating: investigating / 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.
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.
The request body is invalid (code / name is missing, code or name is not a string, isActive is not a boolean, displayOrder is not an integer, code contains characters other than lowercase letters, digits, and underscores, code or name exceeds 255 characters, the body is malformed JSON or not a JSON object (code: "invalid_body"), and so on)
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.
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")
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).
The request body is invalid (code / name is missing, code or name is not a string, isActive is not a boolean, displayOrder is not an integer, code contains characters other than lowercase letters, digits, and underscores, code or name exceeds 255 characters, the body is malformed JSON or not a JSON object (code: "invalid_body"), and so on)
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.
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.
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 five project API endpoints listed here. Calling any other project API returns 403 Forbidden (forbidden).
Retrieves the list of projects within the project restriction. 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).
The body can be omitted. If you send one, make it a JSON object. Fields other than the one below are ignored, except that sending config returns 400 Bad Request (invalid_parameter).
パラメータ
型
必須
説明
payload
any
—
The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. It is converted to a JSON string and attached to the request to the agent of the first step (after a fork, the first step of each lane). The agent receives it as data from outside, not as instructions. Putting a file ID in the request does not attach the file. Omitted or null means no request. Up to 8,000 characters as a JSON string
There are two limits. If payload exceeds 8,000 characters as a JSON string, 400 Bad Request (payload_too_large) is returned. If the whole body exceeds 16 KiB, 413 Payload Too Large (body_too_large) is returned.
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.
Resending with the same key but a different payload returns 409 Conflict (origin_conflict).
The Idempotency-Key length or character set is invalid
400
invalid_parameter
projectId is not a UUID, or config is sent (this API does not accept it; param is config)
400
payload_too_large
payload exceeds 8,000 characters as a JSON string
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
principal_suspended
An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409
start_step_in_branch_lane
The start step is in a lane of a branch step. Set the start step of the time trigger to a step outside the lanes of branch steps
409
definition_pending
The first definition of the project is waiting for approval, so it cannot run yet. Start it after an approver (another owner or an administrator of the organization) approves it in the product screen
409
relink_required
The project cannot be started or resumed until the references that were not found during import are reconnected. The remaining references appear in the project's relink and in the placements' relink. To clear the references that refuse a start: for rows whose kind is "agent", place the agent again (POST /v1/projects/{projectId}/placements); for rows whose kind is "connector", save the connector again on the product screen; for the placements' relink (playbooks and skills that the placed agent points to but were not found), save the agent again with a spec (PATCH /v1/agents/{agentId}; an update that does not send spec does not clear them). Rows whose blocking is false are items to set up again if needed and do not refuse runs; they can be cleared with DELETE /v1/projects/{projectId}/relink, but clearing them alone does not make the project startable
409
branch_ai_unavailable
Branch steps that ask AI cannot run in this environment. Ask an administrator to set up the AI decision for branch steps, or disable those steps in the product screen, then start a new run
409
automation_dlp_enabled
External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration. Until then, a run can start only after the external automation steps are disabled or removed
409
automation_destination_missing
The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step. If no destinations are listed, ask an administrator
409
automation_destination_inactive
The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step
409
admin_stopped
An administrator has stopped the project. Ask an administrator to resume it (this API cannot resume it)
409
unsupported_runtime
The project cannot run in this configuration, for example because agent runtimes are mixed
409
origin_conflict
A different payload was sent with the same Idempotency-Key
429
too_many_active_runs
The project already has the maximum number of runs (3 in total) that are running or awaiting review
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.
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
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
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.
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).
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
principal_suspended
An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409
admin_stopped
An administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it
409
placement_unavailable
The target agent placement does not exist, no execution principal is configured, or the step of the placement is disabled (only a project owner can enable the step; enable it, then retry)
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.
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. However, when an owner or operator (including people with the organization operations role) resumes a "closed_rejected" or "closed_failed" run, the same run returns to "running" (endedAt also returns to null)
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. It returns to null when a closed run is resumed
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
deadlineAt
string | null
Deadline of the workflow run (ISO 8601). null if it has no deadline
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. null for an external automation step
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). It also increases when a closed run is resumed and when the Agent is relaunched after a connection confirmation is approved
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 or of the send of an external automation step. 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. "branch_undecided" when a branch could not decide and a person is asked to choose; "branch_not_selected" for a step in a lane the branch did not choose
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 the review. Set on review step rows and on connection confirmation wait rows (gateKind is "connection"). null for other rows
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)
steps[].resumeCommandId
string | null
The commandId used when this row was started by resuming a closed run. It is set on the rows started by that resume (the step chosen and the other lanes started again). Otherwise null
steps[].resumeReason
string | null
The reason for resuming a closed run. It is set on the same rows as resumeCommandId. Otherwise null
steps[].supersededBy
string | null
"resume" when a row left over from the previous round was closed by resuming a closed run. Otherwise null
steps[].gateKind
string | null
"connection" for a connection confirmation wait row (a row created when the Agent stops before using a connector that requires human confirmation). null otherwise
steps[].connectionConfirmOf
string | null
For a row relaunched after a connection confirmation is approved, the ID of that work item (workItemId). null otherwise
steps[].handoff
object | null
The values and files this step's execution passed to the next step. null when the step has no values and file roles for the next step (outputConfig)
steps[].handoff.values
object
Value name → the returned text (up to 1,000 characters each)
steps[].handoff.files
object
Role name → { filename } (the file name of the file with that role)
steps[].handoff.missing[]
object[]
What did not arrive: name (the value or role name) and reason ("not_returned" (the agent did not return it) / "file_not_found" (not among the output files))
steps[].handoff.truncated
string[]
Names of values cut at 1,000 characters. [] when none
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).
The run does not exist, belongs to another project, or is not accessible
POST/v1/projects/{projectId}/runs/{runId}/cancel
Cancels a workflow run that is running or awaiting review (status is "running" or "waiting_gate"). This is the same as Cancel run on the screen.
When it is cancelled:
The status of the workflow run becomes "cancelled" (cancelled). This cannot be undone, and the workflow run cannot be resumed (only workflow runs closed by a rejection or a failure can be resumed).
Steps in progress are marked failed, and running Agents are told to stop.
Review requests of review steps that have not been decided are withdrawn.
A value to identify resends (8 to 128 characters of letters, digits, and _ . : -)
reason
string
—
The reason for canceling (up to 500 characters)
If you send it for a workflow run that is not running (after it ended or was cancelled), nothing changes: 200 OK is returned with existing set to true. The same applies when you resend after it was cancelled.
If you send it around the same time as another cancel or the end of the workflow run, the choice between 202 Accepted and 200 OK and the value of existing may not match what actually happened. Check the result with status of Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}).
504 Gateway Timeout does not mean "it was not cancelled". Resend with the same commandId, or check status with Get a Workflow Run.
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "commandId": "cancel-20261118-0001",
6 "reason": "Because an error in the input data was noticed"
7}'
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"commandId": "cancel-20261118-0001",
"reason": "Because an error in the input data was noticed"
}'
import requests
response = requests.post(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
headers={"Authorization": f"Bearer {token}"},
json={'commandId': 'cancel-20261118-0001', 'reason': 'Because an error in the input data was noticed'},
)
print(response.json())
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
{
method: "POST",
headers: {
"Authorization": "Bearer " + accessToken,
"Content-Type": "application/json",
},
body: JSON.stringify({"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}),
}
);
const data = await response.json();
console.log(data);
payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
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 and for canceling a workflow run.
When the type is out of scope
Calling trigger fire on a workflow project, or run status or canceling a workflow run 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, 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, a trigger fire with the same eventId and the same body, and a workflow run cancel with the same commandId.
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"
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" } }
When the Request Is Stopped Before Reaching the API
If a layer in front of the API (such as a security inspection) returns an HTML error page, the response is replaced with JSON in the common format above. In that case, error.code is one of the following.
Status
error.code
Description
403
waf_blocked
The request was stopped by a security inspection in front of the API. If the request is legitimate, contact support with error.reference (or the x-request-id response header if it is not present)
4xx and 5xx other than 403
upstream_api_error
The request was rejected by, or caused an error in, a layer in front of the API. If this continues, contact support with error.reference (or the x-request-id response header if it is not present)
Field
Type
Description
error.reference
string
Reference number for a request stopped before reaching the API. Include it when contacting support. Omitted when no value is available
JSON
{ "error":{ "type":"forbidden_error", "message":"The request was blocked by a web application firewall before it reached the API.", "code":"waf_blocked", "suggested_action":"The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.", "reference":"20261018T012345Z-0123456789abcdef" } }
Automatically Recorded Management Operations SaaS
The following management operations automatically generate an audit log entry.
Resource
Operation
action
User
Create
create
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
User
Suspend, resume, and unlock (meta.action is suspend, resume, or unlock)
update
User
Change affiliation and job (meta.action is update-affiliation)