Skip to main content

User API Reference (Projects)

This is the reference for the Marketplace user-facing APIs that handle projects. With an application (sign-in from an external tool) token, you can create and configure projects, place registered Agents, start workflow runs, check the results and artifacts of executions, and decide review requests. For the conversation and organization APIs, see User API Reference (Conversations, Organizations). For how to combine the APIs to investigate and fix executions that did not go well, see the Project API Guide.

A system integration token can call only nine project APIs: list projects, start a workflow run, fire a trigger, get a workflow run, list artifacts, get the content of an artifact, cancel a workflow run, stop a sweep execution of a cycle project, and get the result of an execution (status fields only) (System Integration API Reference). Calling any other API on this page with a system integration token returns 403 Forbidden (forbidden).

Base URL​

All API requests are sent to the base URL below. Replace <your-domain> with the domain of your environment.

Marketplace
https://<your-domain>/api

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

Authentication​

Every API request must include a Bearer token in the Authorization header.

Authorization: Bearer <access_token>

If the token is missing or invalid, 401 Unauthorized is returned. The Marketplace edition applies no scope restrictions.

Call the APIs on this page with a user token obtained through an application (sign-in from an external tool). Sign-in from an external tool is available only in environments where an administrator has opened its entrance (API Setup Guide). Calling them with a user token obtained in any other way (such as the token used when signing in to the Main Screen) returns 404 Not Found for every endpoint. For how to obtain a token, see the Authentication Guide and the Authentication API Reference.

Common Rules​

These rules apply to the APIs on this page.

Who Can Call and 404 / 403​

Whether you can call an operation depends on your role in the project (○ = can call, × = cannot call).

OperationOwnerOperatorMemberOrganization operations role *1Refusal for those who cannot call
Read the project and what is in it (steps, placements, runs, and so on)○○○Partly *2—
Start a workflow run, fire a trigger, and upload a draft of an input file○○○○—
Other operating operations *3○○× (cancelling a workflow run is ○ for the person who started that run)○403 Forbidden (operator_only)
Webhook APIs (including the list and delivery results)○×××403 Forbidden (owner_only). A person with the organization operations role who does not take part gets 409 Conflict (forbidden_role)
Other write APIs (except the API that creates a project)○×××403 Forbidden (owner_only). A person with the organization operations role who does not take part gets 409 Conflict (forbidden_role)
  • *1 A person who has the organization operations role (the "Operations" role assigned under "Admin Roles" in the admin console) in the organization the project belongs to. Even if they do not take part in the project, they can call the operations marked ○ in the table. If a participant also has this role, they can call operating operations in addition to their participation role.
  • *2 For a person with the organization operations role who does not take part, getting the list and contents of deliverables and getting the pending definition approval returns 409 Conflict (forbidden_role), and the contents of a project file returns 400 Bad Request (file_not_found). The agent text and file fields of workflow runs and executions are returned as null or empty.
  • *3 Setting the deadline of a workflow run, reassigning approvers, cancelling a workflow run, stopping the execution of a cycle sweep, and pausing and resuming a project.
  • Who can call the work item, queue, and connector APIs is described in each section.
SituationWhat is returned
A project of which you are neither a member nor a person with the organization operations role in its organization, and a project that does not existBoth return 404 Not Found, and they cannot be told apart from the response. However, for a published project, even a non-member can read only the structure with Get project (GET /v1/projects/{projectId})
404 Not Found codeOne per endpoint, and it is the name of the last resource in the path (for example, the placement API returns placement_not_found and the execution API returns execution_not_found). An endpoint whose path has no resource ID returns project_not_found. The API that writes a step setting under a placement (runtime-config) returns placement_not_found even though the last part of the path is a step ID. When the project is not visible, the code of that endpoint is returned as well
An ID specified in the body (registered agent, step, user, and so on) does not exist or is not visibleIt differs by endpoint (for example, for a placement, marketplaceAgentId returns 400 Bad Request (agent_not_found) and stepIds returns 400 Bad Request (invalid_parameter)). See the description and error responses of each endpoint
A nonexistent ID specified in a list filter query (placement_id, step_id, run_id)An empty list is returned
The token of a user whose record in the main service is not linked to an account of the authentication server403 Forbidden (sso_required) is returned by the project, work item, and queue APIs (except getting the project list, starting a workflow run, firing a trigger, and getting a workflow run). Logging in to the main screen once links the account

"Not a member" in the 404 rows of the error tables on this page means that the person is neither a member nor a person with the organization operations role in the organization the project belongs to.

Request Handling​

Send the body as a JSON object (the API that uploads input files uses multipart/form-data).

What you sentHow it is handled
Query parameters and body fields not in the specificationIgnored
An invalid value for a query parameter in the specification, or a cursor that cannot be read400 Bad Request
An invalid URL encoding in a path parameter value (a % sequence)400 Bad Request (invalid_parameter)
A body other than Content-Type: application/json, or a body with an unsupported character set (charset)415 Unsupported Media Type (unsupported_media_type)
Malformed JSON, or a body that is not a JSON object400 Bad Request (invalid_body)
A field that this API has decided not to accept400 Bad Request (invalid_parameter). It is not silently ignored because you would believe it was changed when it was not. The fields concerned are described in each endpoint
Query namessnake_case (my_role, placement_id, step_id, run_id, project_id). The previous names (myRole, placementId, stepId, runId, projectId) are also accepted. Specifying different values for both names returns 400 Bad Request (invalid_parameter)

The body limits are as follows. A larger body returns 413 Payload Too Large (body_too_large).

APIBody limit
Create a project, import a definition, decide a work item, extend a deadline3 MiB
Add or change a step32 KiB
Replace the case configuration of a workflow run waiting for confirmation787,456 bytes
Upload an input fileSee the description of that API
Other APIs16 KiB

Editing and Resending​

For the APIs that change something, put the digest returned by the get API into baseDigest and send it. If another change was made after you got it, 409 Conflict (stale_base) is returned. Get it again and resend.

  • The digest in the response is the value after the edit. You can use it for the next edit.
  • Two changes that arrive at almost the same time may both succeed.
  • Extending a work item deadline and setting a workflow run deadline or reassigning approvers do not use baseDigest (they are not compared with changes made after you got it). Replacing the case configuration of a workflow run waiting for confirmation does not use baseDigest; put the revision read from getting the case configuration into expectedRevision and send it.
  • In a tenant where changes to the definition require approval, check that a change arrived by getting with definition=pending (a change waiting for approval does not appear in the default get).

Resends are handled as follows.

APIWhat identifies a resendResending with the same value
Start a workflow runThe Idempotency-Key header (required)The result of the first request is returned
Fire a triggereventId in the bodyThe result of the first request is returned
Decide a work item, reassign approvers, cancel a workflow run, replace the case configuration of a workflow run waiting for confirmationcommandId in the bodyThe result of the first request is returned (see the description of each endpoint for how it is returned)
Upload an input fileThe Idempotency-Key header (optional)The result of the first request is returned
Place a registered agentThe same registered agent and the same assigned stepThe existing placement is returned
Create a project, create a step—Another one is created. Before resending, check whether it was created by listing or getting the projects

Fields About People​

  • User names and email addresses are returned only in the member list (members) of Get Project (GET /v1/projects/{projectId}). Other fields return only user IDs.
  • The owner of a resource is ownerUserId (the owner of a placed Agent is agentOwnerUserId), people in settings are approverUserIds and escalateToUserId, and the requester of a review request is requesterUserId.
  • Who did something is returned as a pair of …Kind (kind) and …Ref (reference). When …Kind is "human", …Ref is a user ID. Otherwise, …Ref is client:<integration ID> for a system integration, or another reference such as system:…. Even when there is no value, the field is not omitted and is returned as null. As an exception, what started a workflow run is returned only as startedByRef (there is no kind field; see Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}) for the values).

Pagination​

ParameterTypeDescription
limitintegerNumber of items per page (1-100). Defaults to 50.
cursorstringCursor value for the next page. Pass the cursor from the previous response as is.
  • cursor is returned only when hasMore is true. The total count of the list is not returned.
  • Lists whose limit range or default is different, lists without limit, lists that return all items, and lists that cannot be continued (where hasMore means something different) are described in each endpoint.

Projects​

A project is a unit for running work by placing Agents in steps. There are two types: workflow (steps run in order) and cycle (each placement keeps running in sweeps). The type is decided when the project is created and cannot be changed later.

Endpoint List​

メソッドエンドポイント説明
GET/v1/projectsList the projects you participate in
GET/v1/projects/sharedList shared projects
GET/v1/projects/organizationsGet the organizations you can set on a project
GET/v1/projects/{projectId}Get a project
POST/v1/projectsCreate a project
PATCH/v1/projects/{projectId}Edit a project
DELETE/v1/projects/{projectId}Delete a project
GET/v1/projects/{projectId}/controlGet the control settings
GET/v1/projects/{projectId}/definitionExport the definition of a project
POST/v1/projects/importCreate a project from an exported definition (import)
DELETE/v1/projects/{projectId}/relinkClear the relink items to set up again if needed
GET/v1/projects/{projectId}/definition-approvalGet the pending definition approval
DELETE/v1/projects/{projectId}/definition-approvalWithdraw the pending definition change

GET/v1/projects

Retrieves the list of projects you take part in (projects you can read through the organization operations role are not listed). 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​

ParameterTypeDefaultDescription
limitinteger50Number of items to retrieve (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)
my_rolestring—One of "owner", "operator" or "member". Returns only the projects where the caller has that role (the earlier name myRole is also accepted)

Any other query parameter is ignored. A value other than "owner" / "operator" / "member", specifying my_role more than once, or giving different values to my_role and myRole returns 400 Bad Request.

cursor represents a position, so do not change my_role while reusing the same cursor. Changing the criteria changes the result set and can duplicate or skip items.

Request Example​

List projects
1curl "https://<your-domain>/api/v1/projects?limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
projectsarrayArray of project objects
projects[].projectIdstringProject ID (UUID)
projects[].namestringProject name
projects[].typestring"workflow" or "cycle"
projects[].statusstringProject state. One of "active", "paused", "archived" or "admin_stopped" (stopped by an administrator)
projects[].tagsarrayArray of tags. An empty array when none are set
projects[].myRolestringThe caller's own role in that project: "owner", "operator" or "member"
projects[].ownersarrayUser IDs of the project's current owners. Participants who are not owners are not included
hasMorebooleanWhether a next page exists
cursorstringCursor 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": [],
"myRole": "owner",
"owners": ["bbbe4306-6975-420b-af47-fb4c8f48b4aa"]
},
{
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "Always-on inquiry handling",
"type": "cycle",
"status": "active",
"tags": [],
"myRole": "member",
"owners": ["90b40fd8-a6b8-42b8-ab61-f3b674169b43", "463e2c25-5a80-4362-b77e-941df96fb1f2"]
}
],
"hasMore": false
}

Error Responses​

StatusDescription
400limit is outside 1-100, or cursor or my_role is invalid (code is invalid_parameter)

GET/v1/projects/shared

Lists shared projects (your own projects are included if they are shared). A project shared only with organizations is listed only for users in those organizations. Cursor-based pagination is supported.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of items per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)
typestring—Filter by "cycle" or "workflow"
tagstring—Filter to projects with this tag (up to 30 characters, not counting leading and trailing whitespace or a leading #; case-insensitive)
qstring—Filter by part of the name or description (up to 100 characters)
sortstring"popular"Sort order. "popular" is by the number of copies (then by update time, newest first), and "new" is by update time, newest first

Request Example​

List shared projects
1curl "https://<your-domain>/api/v1/projects/shared?type=workflow&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
projectsarrayArray of projects
projects[].projectIdstringProject ID (UUID)
projects[].namestring | nullProject name
projects[].descriptionstring | nullDescription
projects[].typestring | null"workflow" or "cycle"
projects[].statusstring | nullOne of "active", "paused", "archived", or "admin_stopped" (stopped by an administrator)
projects[].tagsarrayArray of tags
projects[].shareScopestring | nullWho the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)
projects[].shareOrganizationsarray | nullArray of the organization codes it is shared with. Used when shareScope is "organizations"
projects[].stepCountnumber | nullNumber of enabled steps
projects[].agentCountnumber | nullNumber of placements
projects[].copyCountnumber | nullNumber of times copied
projects[].connectorCountnumber | nullNumber of connectors
projects[].ownerUserIdstring | nullUser ID of the owner
projects[].updatedAtstring | nullLast updated time (ISO 8601)
hasMorebooleanWhether there is a next page
cursorstringCursor for the next page. Included only when hasMore is true

myRole and owners are not included, even for projects you are a member of.

Response Example​

JSON
{
"projects": [
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "Invoice reconciliation",
"description": "Matches invoice amounts against line items and turns differences into work items",
"type": "workflow",
"status": "active",
"tags": [
"Accounting"
],
"shareScope": "all",
"shareOrganizations": null,
"stepCount": 3,
"agentCount": 2,
"copyCount": 5,
"connectorCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"updatedAt": "2026-11-18T01:00:00.000Z"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterAn invalid value for limit, cursor, type, tag, q, or sort
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server

GET/v1/projects/organizations

Gets the organizations you can set when creating a project. Only the organization the calling user currently belongs to can be set (zero or one item). This differs from GET /v1/organizations, which returns all organizations.

Request Example​

Get project organizations
1curl https://<your-domain>/api/v1/projects/organizations \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
organizationsarrayArray of organizations
organizations[].valuestringOrganization code (specify this in organizationCode of a project)
organizations[].labelstring | nullOrganization name
hasMorebooleanAlways false

Response Example​

JSON
{
"organizations": [
{
"value": "eng",
"label": "Engineering"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
503organization_unavailableThe organization the user belongs to cannot be confirmed (resend the request later)

GET/v1/projects/{projectId}

Gets a project together with its steps, members, placements, triggers, notifications, and connectors. If a user who is not a member specifies a shared project, only the structure (a preview) is returned. A person with the organization operations role for the project's organization can read all of it, not a preview, even without taking part in the project (myRole is null and orgOperator is true).

Path Parameters​

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

Query Parameters​

パラメータ型必須説明
definitionstring—With "pending", returns the view with the pending definition change laid over it (the approved definition if nothing is pending). Without it, returns the approved definition

Request Example​

Get project
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
projectobjectThe project (the table below)
stepsarrayArray of steps (in order). See "Step Fields" for the fields of an item
stepsDigeststringA value for the order of the steps. Send it as baseDigest when reordering steps
membersarrayArray of members
members[].userIdstringUser ID
members[].rolestring | null"owner", "operator" or "member"
members[].joinedAtstring | nullWhen the user became a member (ISO 8601)
members[].namestring | nullUser name
members[].emailstring | nullUser email address
placementsarrayArray of placements. See "Placement Fields" for the fields of an item
triggersarrayArray of triggers (time and webhook triggers only)
triggers[].triggerIdstring | nullTrigger ID (UUID). Used to fire, change, and delete the trigger
triggers[].typestring"cron" (time) or "webhook"
triggers[].namestring | nullName
triggers[].enabledboolean | nullWhether it is enabled
triggers[].lastFiredAtstring | nullWhen it last fired (ISO 8601)
triggers[].nextFireAtstring | nullWhen it is scheduled to fire next (ISO 8601)
triggers[].createdAtstring | nullCreation time (ISO 8601)
triggers[].cronstring | nullCron expression ("cron" triggers only)
triggers[].timezonestring | nullTime zone ("cron" triggers only)
triggers[].startStepIdstring | nullID of the step to start from ("cron" triggers only)
triggers[].placementIdstring | nullID of the placement to start ("webhook" triggers only)
triggers[].stepIdstring | nullID of the step to start ("webhook" triggers only)
triggers[].startFailureobject | nullStart failure ("cron" triggers only). Set only when a start failed; otherwise null. See "Reading start failures" below
triggers[].startFailure.reasonstring | nullCode of the reason the run could not start
triggers[].startFailure.sincestring | nullWhen runs stopped starting for this reason (ISO 8601)
triggers[].digeststringThe value to send as baseDigest when changing the trigger
stepStartFailuresarrayStart failures of runs that start at the time set on the first step. Only steps that could not start are included. See "Reading start failures" below
stepStartFailures[].stepIdstring | nullStep ID
stepStartFailures[].reasonstring | nullCode of the reason the run could not start
stepStartFailures[].sincestring | nullWhen runs stopped starting for this reason (ISO 8601)
notificationsobjectNotification settings
notifications.gateReachedboolean | nullWhether to notify when a review request arrives
notifications.gateDueSoonboolean | nullWhether to send a reminder when a review request nears its deadline (null with an earlier version of the platform)
notifications.gateOverdueboolean | nullWhether to notify when a review request passes its deadline
notifications.runDeadlineOverdueboolean | nullWhether to notify when a workflow run passes its deadline
notifications.runStalledboolean | nullWhether to notify when a workflow run stalls (makes no progress for limits.stallHours)
connectorsarrayArray of connectors registered to this project
connectors[].kindstring | null"mcp" or "a2a"
connectors[].connectionIdstring | nullConnector ID. Read its contents with the connector API (GET /v1/connectors/{kind}/{connectionId}). null for a connector disabled or deleted in the admin console, and when the connector information could not be checked
connectors[].namestring | nullConnector name
connectors[].ledgerEnabledboolean | nullWhether the connector is used as a ledger
connectors[].confirmModestring | nullThe setting for whether a person is asked to confirm before this connector is used: "none", "first_per_execution", or "always". Set it in the UI
connectors[].confirmWaitMinutesnumber | nullMaximum time to wait for that confirmation (minutes)
connectors[].loginstring | nullSign-in status: "connected" (signed in), "reauth_required" (must sign in again), or "not_connected" (not signed in). null when the status cannot be confirmed. Sign in on the screen
connectors[].createdAtstring | nullRegistration time (ISO 8601)
definitionViewstring | nullOnly with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined
relinkobject | nullFor a project imported from an exported definition, the references that were not found in this environment and must be reconnected. null if there are none
relink.itemsarrayArray of the references to reconnect
relink.items[].kindstringKind of the reference. "connector" (a connector that was not found) and "agent" (a registered agent that was not found) refuse to start or resume runs until reconnected. "connection", "playbook_version", "automation_destination", "approvers", "branch_target", "external_wait", "trigger", "library", "input_files", "placement_env", "lanes", "connection_binding" and "input_binding" are items to set up again if needed and do not refuse runs. "branch_target" means that the lane steps of a branch step were not found, so the lanes and conditions were removed. "unavailable" means that something not available in this environment's version, or a time trigger of a cycle definition (what is "cron_trigger"), was removed
relink.items[].blockingbooleanIf true, runs are refused to start or resume. Not present in rows whose kind is "unavailable"
relink.items[].*—Depending on the kind of row, hint fields (agent, name, step, what, from, to, type, count, names and agents) are present. Only names, versions and counts; no IDs or URLs. names holds only the names of environment variables, not their values

A member (member) can also start workflow runs, fire webhook triggers, upload input-file drafts and cancel workflow runs they started. An operator (operator) can, in addition, cancel workflow runs others started, set workflow run deadlines, reassign reviewers, and pause or resume the project (changing status alone). Project settings, steps, agent placements, triggers, webhooks, sharing and deletion and step settings are for owners only (members can still pass a case's own parameters, connections and input files with config at the start). People with the organization operations role can also call the operator operations without taking part in the project. A member without the organization operations role calling an operator operation gets 403 Forbidden (operator_only).

Fields of project:

FieldTypeDescription
projectIdstringProject ID (UUID)
namestring | nullProject name
descriptionstring | nullDescription
tagsarrayArray of tags
typestring | null"workflow" or "cycle"
statusstring | nullOne of "active" (active), "paused" (paused), "archived" (archived), or "admin_stopped" (stopped by an administrator)
adminStopobject | nullWhen an administrator has stopped the project: where it was stopped from, why, and when. null if it is not stopped. Returned only by Get Project
adminStop.sourcestring | nullWhere it was stopped from. "aster" (an AGENTIC STAR administrator), or a connected service: "agent365" or "aws"
adminStop.reasonCodestring | nullThe kind of reason. "admin" (an administrator stopped it), "remote_stopped" (it was stopped in the connected service), or "remote_unreachable" (the connected service cannot be reached)
adminStop.reasonstring | nullThe reason text. null if there is none
adminStop.stoppedAtstring | nullWhen it was stopped (ISO 8601)
policyobject | nullExecution rules. Returned as set on the screen. Cannot be changed with this API
limitsobject | nullExecution limits
limits.maxRetriesPerStepnumberMaximum number of retries when a step fails
limits.maxSendBacksPerStepnumberMaximum number of times work can be sent back to the same step
limits.runDeadlineHoursnumber | nullDefault deadline of a workflow run (hours from its start). No deadline is set if null or absent
limits.stallHoursnumberHours without progress after which a run is treated as stalled (24 if absent)
languagestring | nullLanguage of the project
flowStructureobject | nullAlways null
reportTargetsobject | nullNot used at present (even if it has a value, the value is not used)
escalateToUserIdstring | nullUser ID of the default contact of the project (the contact for overdue review requests. Cannot be changed with this endpoint)
organizationCodestring | nullOrganization code
organizationNamestring | nullOrganization name
isSharedboolean | nullWhether it is shared
shareScopestring | nullWho the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)
shareOrganizationsarray | nullArray of the organization codes it is shared with. Used when shareScope is "organizations"
copyCountnumber | nullNumber of times copied
ownerUserIdstring | nullUser ID of the owner
myRolestring | nullRole of the calling user: "owner", "operator" or "member". null in a preview and for a person with the organization operations role who does not take part in the project
orgOperatorbooleanWhether the calling user has the organization operations role for the project's organization. Returned only by Get Project (not in the list)
createdAtstring | nullCreation time (ISO 8601)
updatedAtstring | nullLast updated time (ISO 8601)
digeststringThe value to send as baseDigest when editing the project

Reading start failures (triggers[].startFailure and stepStartFailures):

These record times when a workflow run could not start on schedule. There are two kinds: time triggers ("cron") and the time set on the first step (the step's schedule).

  • A value is set only when the last start record in the past 90 days for that trigger (step) is a failure. After a successful start, and before the time has ever come, startFailure is null and the step is not in stepStartFailures.
  • While the same reason continues, only the first occurrence is recorded. since is when runs stopped starting for that reason, and it changes when the reason changes. If runs have not started for the same reason for more than 90 days, the record is older than 90 days, so the value is null (not included).
  • A start skipped for a reason that is not recorded, such as the project being paused or the limit on concurrent runs being reached, does not change the value (a previous failure stays a failure, and null stays null after a successful start).
  • Runs start at the time set on the first step only when there is no enabled time trigger. While an enabled time trigger exists, stepStartFailures shows earlier records. It can also include the ID of a deleted step.

Main values of reason. Other values can also be returned.

ValueMeaning
approvers_requiredA human review step has no reviewer who is still a member
unsupported_runtimeAn Agent of a kind this service cannot run is placed
unexpected_errorAn unexpected failure

When a user who is neither a member nor a person with the organization operations role reads a shared project (a preview), project (without organizationName, digest, and adminStop; myRole is null), steps (without the digest of each step), and placements (only placementId, agentId, name, description, goal, stepIds, and skillCount) are returned. stepsDigest, members, triggers, stepStartFailures, notifications, connectors, and relink are not returned.

Response Example​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "Invoice reconciliation",
"description": "Matches invoice amounts against line items and turns differences into work items",
"tags": [
"Accounting"
],
"type": "workflow",
"status": "active",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T01:00:00.000Z",
"organizationName": "Engineering",
"digest": "Jkc7kvIS8kGx0qVHnZ6-Cva5kuuP8yGAiGSmrMC7g18",
"adminStop": null,
"orgOperator": false,
"relink": null
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "Difference check",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "Difference report",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
}
],
"stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
"members": [
{
"userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"role": "owner",
"joinedAt": "2026-11-10T09:00:00.000Z",
"name": "Taro Tanaka",
"email": "tanaka@example.com"
}
],
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
],
"triggers": [],
"stepStartFailures": [],
"notifications": {
"gateReached": true,
"gateDueSoon": true,
"gateOverdue": true,
"runDeadlineOverdue": true,
"runStalled": true
},
"connectors": []
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or it is a project that is not shared and you are not a member of

GET/v1/projects/{projectId}/definition

Returns the confirmed (approved) definition of a project as the same JSON as "Export definition" on the screen. Only owners can call it. The returned definition can be used as is in the body of the import (POST /v1/projects/import). It cannot be called with a system integration token.

  • definition is returned in the export format of the product (format is "agentic-star.project-definition", with a format version). The field names are not converted to camelCase.
  • Reviewers, report destination addresses, connections, values of environment variables and the like are not included. However, the agentConfig of agents, the connection IDs in execution rules, and text written by users are included as is. If you put a secret in agentConfig, it is also in the export. In another environment, the same connection ID can point to something else. This response has Cache-Control: no-store.

Path Parameters​

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

Request Example​

Export project definition
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
definitionobjectThe definition of the project (in the export format of the product)

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not in UUID format
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, you are not a member, or there is no confirmed definition

POST/v1/projects/import

Creates a project from an exported definition (the definition of GET /v1/projects/{projectId}/definition). Same as "Import from file" on the screen. Anyone who can create projects can call it (the caller becomes the owner). It cannot be called with a system integration token. Idempotency-Key is not accepted.

  • The created project is paused (status is "paused"), and its time triggers and sweeps are disabled. Check it, then resume it.
  • References that are not found in this environment (connectors, agents, playbooks, skills and so on) are not brought in and appear in relink of the response. While references that refuse runs remain, runs cannot start (409, relink_required).
  • The project in the response is the project right after creation. Before changing the imported project, read it again with Get Project (GET /v1/projects/{projectId}) and send that digest as baseDigest.
  • If no response came back (a timeout or a cut connection), the project may have been created. Check the list of projects (GET /v1/projects) before retrying.

Request Body​

FieldTypeRequiredDescription
definitionobjectRequiredThe exported definition (the definition of the export response as is)
organizationCodestring | null—Code of the organization. Same as organizationCode of the API that creates a project

Response (201 Created)​

FieldTypeDescription
projectobjectThe created project. Same fields as project in the response of the API that creates a project
relinkobjectReferences to reconnect
relink.itemsarrayArray of the references to reconnect. The fields of a row are the same as relink.items of Get Project
relink.agentsarrayFor each placed agent, the playbooks and skills that were not found
relink.agents[].agentstringName of the agent
relink.agents[].playbookobject | nullThe playbook that was not found (name and versionNo)
relink.agents[].skillsarrayArray of the skills that were not found (name and versionNo)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, the first definition of the created project becomes pending and this holds its state (see Definition approval fields). null when no approval is required

Response Example​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "Invoice reconciliation",
"description": "Matches invoice amounts against line items and turns differences into work items",
"tags": [
"Accounting"
],
"type": "workflow",
"status": "paused",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T01:00:00.000Z",
"digest": "rvH500_xTzkSk08IMptBslK03TyQg7yiaYVT8yBtPsI"
},
"relink": {
"items": [],
"agents": []
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterdefinition is not an object, or the type or length of organizationCode is wrong
400invalid_bodyThe body is malformed JSON or not a JSON object
400invalid_definition_fileThe shape of the definition is not valid
400unsupported_definition_versionThe format version of the definition cannot be handled in this environment. Align the versions of the environment that exported it and the one that imports it
400definition_too_largeThe definition is too large (more than 200 operations to create). Make the definition smaller
400organization_not_memberAn organization that cannot be set was specified
400import_failedA write while creating the project was refused. error.message says which operation was refused and why (if the original failure was a 5xx, the same 5xx is returned)
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedThe definition has a trigger or a step with a schedule (any step), but an administrator has not permitted scheduled run creation (sweeps are always disabled on import, so they do not cause this). It is refused before anything is created, so no partly created project is left
409project_limit_reachedThe number of projects has reached the limit (the number is in error.message)
413body_too_largeThe body exceeds 3 MiB
415unsupported_media_typeThe Content-Type of the body is not application/json
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while

From the relink of an imported project, clears only the items to set up again if needed, which do not refuse runs (rows whose blocking is false; the same as "Mark as reviewed" on the screen). Only owners can call it. References that refuse runs (rows whose blocking is true) and the placements' relink (playbooks and skills that a placed agent points to and that were not found) remain. Clearing these alone does not let runs start. It cannot be called with a system integration token.

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

Request Example​

Dismiss project relink
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/relink \
2-H "Authorization: Bearer <access_token>"
JSON
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"dismissed": true
}
StatuscodeDescription
400invalid_parameterprojectId is not in UUID format
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

POST/v1/projects

Creates a project. The user who creates it becomes the owner and the principal that runs the project. Choose an Agent from the Agent candidates (GET /v1/projects/agent-candidates), and then place it with the API that places a placement (POST /v1/projects/{projectId}/placements).

Request Body​

FieldTypeRequiredDescription
namestringYesProject name (up to 255 characters; cannot be only whitespace)
descriptionstring—Description (up to 5000 characters)
tagsarray—Tags (up to 10 strings of up to 30 characters each; saved in lowercase with leading and trailing whitespace and a leading # removed. Tags that become empty or the same this way cannot be sent)
typestring—"cycle" or "workflow". "cycle" if omitted
organizationCodestring | null—Organization code (up to 255 characters). Only an organization returned by GET /v1/projects/organizations can be set. null, an empty string, or only whitespace is the same as not setting one
stepsarray—The steps (up to 12). When a non-empty array is given, a workflow needs at least 2 steps and a cycle at least 1. If omitted or empty, the project is created with the default steps (for a workflow, three steps: a step run by an Agent, a review step, and a step run by an Agent; for a cycle, two steps run by Agents)
steps[].namestring | null—Step name (up to 100 characters; an empty string or null means the default name; cannot be only whitespace)
steps[].descriptionstring | null—Step description (an empty string or null means no description)
steps[].enabledboolean—Whether it is enabled (true or false). Enabled if omitted
steps[].zonestring—"ai" (run by an Agent) or "gate" (review step). "ai" if omitted. Only "ai" for cycle. null cannot be sent
steps[].outputConfig——Cannot be sent (anything other than null is 400 output_config_invalid; null is the same as not sending it)

trigger, policy, agents, guardrail, and templateRef are not accepted (sending them returns 400, invalid_parameter). Set execution rules on the screen. Add triggers after creating the project, with the API that creates a trigger (POST /v1/projects/{projectId}/triggers). For a cycle, set the sweep interval after placing Agents, with the API that changes the sweep (PATCH /v1/projects/{projectId}/placements/{placementId}/schedule).

Request Example​

Create project
1curl -X POST https://<your-domain>/api/v1/projects \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "Invoice reconciliation",
6 "description": "Matches invoice amounts against line items and turns differences into work items",
7 "tags": [
8 "Accounting"
9 ],
10 "type": "workflow",
11 "organizationCode": "eng"
12}'

Response (201 Created)​

FieldTypeDescription
projectobjectThe created project. Same fields as project in Get Project (without organizationName and adminStop; myRole is "owner")
stepsarrayArray of the created steps. See "Step Fields" for the fields of an item
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, the first definition of the created project becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs cannot start. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "Invoice reconciliation",
"description": "Matches invoice amounts against line items and turns differences into work items",
"tags": [
"Accounting"
],
"type": "workflow",
"status": "active",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-18T05:00:00.000Z",
"updatedAt": "2026-11-18T05:00:00.000Z",
"digest": "Jkc7kvIS8kGx0qVHnZ6-Cva5kuuP8yGAiGSmrMC7g18"
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "rBZ_uP64l5OjdSlPVOdAoWThVePY0Rqei1BltLAcvQg"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": null,
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "klTw4jQoxuF17jBz4GL9aYU5DcFDjcv24zXfBEWTMtw"
}
],
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parametername is missing or only whitespace, a field has the wrong type, length, number of items, or value (including empty or duplicate tags), more than 12 steps or a non-empty steps array with fewer than the minimum (2 for workflow, 1 for cycle), or trigger, policy, agents, guardrail, or templateRef was sent
400invalid_bodyThe body is malformed JSON or not a JSON object
400cycle_gate_not_allowedA review step ("gate") was specified for a cycle
400output_config_invalidsteps[].outputConfig was sent (not available in the Marketplace edition; null is the same as not sending it). error.param is steps[N].outputConfig
400organization_not_memberAn organization that cannot be set was specified
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
409project_limit_reachedThe number of projects has reached the limit (in the Marketplace edition, 5 per environment; archived projects are not counted; the numbers are in error.message)
413body_too_largeThe body exceeds 3 MiB
415unsupported_media_typeThe Content-Type of the body is not application/json
503organization_unavailableThe organization the user belongs to cannot be confirmed
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while

PATCH/v1/projects/{projectId}

Edits a project. Only the fields you send are changed. Only owners can call this API, except that operators and people with the organization operations role can also pause or resume the project by sending only baseDigest and status ("active" or "paused").

Path Parameters​

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

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesproject.digest from Get Project
namestring—Project name (up to 255 characters; cannot be empty or only whitespace)
descriptionstring—Description (up to 5000 characters; cannot be an empty string, only whitespace, or null)
tagsarray—Tags (same as when creating). Sending them replaces all tags
statusstring—"active", "paused", or "archived"
isSharedboolean—Whether to share it
shareScopestring—Who the project is shared with: "all" (everyone) or "organizations" (only users in shareOrganizations)
shareOrganizationsarray—Organization codes it is shared with (up to 20, each up to 255 characters; surrounding whitespace is removed and duplicates are merged). Sending it replaces the whole list. At least one is required when the item is shared with the scope "organizations", and when it is sent together with shareScope "organizations"
limitsobject—Execution limits. Only the fields you send are overlaid on the current values
limits.maxRetriesPerStepinteger—0 to 10
limits.maxSendBacksPerStepinteger—1 to 10
limits.runDeadlineHoursinteger | null—1 to 2160. null sets no deadline
limits.stallHoursinteger—1 to 720
organizationCodestring | null—Organization code (up to 255 characters). Can be set only once, on a project that has no organization yet. Sending the current value changes nothing (you can send back the value you got). Sending a different value to a project that already has an organization returns 409 (organization_locked). null changes nothing if no organization is set yet, and returns 409 (organization_locked) if one is set

Send at least one field besides baseDigest. type, policy, connectSecret, and a non-null limits.maxMinutesPerRun are not accepted (sending them returns 400, invalid_parameter). The length of one agent's work cannot be changed in the project. The type is decided when the project is created, and execution rules are changed on the screen.

Setting status to "paused" or "archived" stops new executions from starting. Sweeps and time-based starts stop, starting workflow runs and firing triggers are refused with 409 Conflict (a resend of a workflow run start with the same Idempotency-Key as an accepted one returns the result of the first request). Running executions are not stopped. A running workflow run waits without starting its next step (its status stays "running" or "waiting_gate"). Fires accepted before the stop may still run after it. Setting it back to "active" resumes the starts that were held while the project was stopped.

While an administrator has stopped the project (status is "admin_stopped"), an edit that sends status and deleting the project are refused with 409 Conflict (admin_stopped). Other fields, such as the name, can be changed. An administrator resumes the project.

Request Example​

Update project
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "Jkc7kvIS8kGx0qVHnZ6-Cva5kuuP8yGAiGSmrMC7g18",
6 "status": "paused"
7}'

Response (200 OK)​

FieldTypeDescription
projectobjectThe project after the edit. Same fields as project in Get Project (without organizationName and adminStop)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"project": {
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"name": "Invoice reconciliation",
"description": "Matches invoice amounts against line items and turns differences into work items",
"tags": [
"Accounting"
],
"type": "workflow",
"status": "paused",
"policy": {
"profile": "open",
"deny": []
},
"limits": {
"maxRetriesPerStep": 2,
"maxSendBacksPerStep": 3,
"runDeadlineHours": null,
"stallHours": 24
},
"language": "ja",
"flowStructure": null,
"reportTargets": {
"app": true
},
"escalateToUserId": null,
"organizationCode": "eng",
"isShared": false,
"shareScope": null,
"shareOrganizations": null,
"copyCount": 0,
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"myRole": "owner",
"createdAt": "2026-11-10T09:00:00.000Z",
"updatedAt": "2026-11-18T05:30:00.000Z",
"digest": "rvH500_xTzkSk08IMptBslK03TyQg7yiaYVT8yBtPsI"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name was set empty or only whitespace, description was set to an empty string, only whitespace, or null, null was sent for name, status, tags, isShared, or limits, a field has the wrong type or value (including empty or duplicate tags), or type, policy, connectSecret, or limits.maxMinutesPerRun (other than null) was sent
400invalid_bodyThe body is malformed JSON or not a JSON object
400invalid_share_scopeshareScope is not "all" or "organizations"
400invalid_share_organizationsshareOrganizations is not an array, has 21 or more items, or has a value that is not a string, is empty or only whitespace, or is 256 characters or longer
400share_organizations_required"organizations" was sent for shareScope with an empty shareOrganizations, or the item is shared (isShared is true in the sent or current value) while the scope is "organizations" and there is no organization (the sent and current values are combined)
400organization_not_memberAn organization that cannot be set was specified
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner sent a change that sets status to "archived" or includes an updatable field (in the request body table above) other than status
403operator_onlyA member who is neither an owner nor an operator and does not have the organization operations role sent a change that only pauses or resumes the project
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409stale_baseThe project has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
409relink_requiredReferences missing after the import must be reconnected before the project can resume from a pause (status set to "active"). For how to fix it, see relink_required in the error table of starting a workflow run
409admin_stoppedAn administrator has stopped the project (its status cannot be changed)
409organization_lockedAn organization is already set (a different value or null was sent)
409project_limit_reachedTried to move the project out of "archived", but the number of projects has reached the limit (in the Marketplace edition, 5 per environment; the numbers are in error.message)
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
503organization_unavailableThe organization the user belongs to cannot be confirmed
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

DELETE/v1/projects/{projectId}

Deletes a project. Only owners can call this API. What is running (sweeps, running workflow runs, review requests waiting for a decision, and triggers) stops. Records of executions and reviews are not deleted. The service also tries to remove sign-ins to the project's connectors, but the deletion of the project succeeds even if they cannot be removed.

Path Parameters​

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

Request Example​

Delete project
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31 \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

JSON
{
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"deleted": true
}

Calling it again returns 404 Not Found.

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, you are not a member, or it has already been deleted
409legal_holdThe project is under legal hold. It cannot be deleted until an administrator releases the hold
409admin_stoppedAn administrator has stopped the project. It cannot be deleted until an administrator resumes it

GET/v1/projects/{projectId}/control

Gets the control settings of a project (the strength of the execution rules and the settings of review steps).

Path Parameters​

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

Query Parameters​

パラメータ型必須説明
definitionstring—With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition

Request Example​

Get project control
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/control \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
tenantProfilestring | nullBase rule for the whole tenant: "open", "guarded", or "strict". null when it cannot be confirmed
tenantSourcestring | nullWhere tenantProfile comes from: "governance_policies" (set in the admin console), "default" (no setting, so the default), or "unavailable" (cannot be confirmed)
projectProfilestring | nullBase rule of this project
effectiveProfilestring | nullThe base rule actually in effect (the stricter of the tenant and this project). null when tenantProfile is null
denyarrayOperations prohibited by the execution rules
gatesarrayArray of enabled review steps
gates[].stepIdstringStep ID
gates[].positionnumberPosition of the step
gates[].namestringStep name
gates[].gateKindstringKind of review: "review" (review) or "manual" (manual work)
gates[].modestring"blocking" (wait for the reviewer's decision). "notify_only" saved in an earlier version may be returned, but workflow runs always wait for the reviewer's decision regardless of the value
gates[].overdueActionstring"none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting). A value saved in an earlier version may be returned, but in workflow runs nothing is decided automatically after the deadline regardless of the value; the reviewers are notified and it keeps waiting
gates[].approverUserIdsarrayArray of user IDs of the reviewers
gates[].deadlineHoursnumber | nullDeadline (hours)
operationClassesnullNot used at present (always null)
definitionViewstring | nullOnly with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined

Response Example​

JSON
{
"tenantProfile": "guarded",
"tenantSource": "default",
"projectProfile": "guarded",
"effectiveProfile": "guarded",
"deny": [],
"gates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "Amount check",
"gateKind": "review",
"mode": "blocking",
"overdueAction": "none",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"deadlineHours": 24
}
],
"operationClasses": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409definition_invalidWith definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason)
503definition_busyWith definition=pending, another change to the same definition is in progress. Retry after a while

GET/v1/projects/{projectId}/definition-approval

Gets a summary of the definition change pending approval. Members can call it. When the tenant requires approval for definition changes, changes made by the write APIs (project, steps, placements, triggers and library bindings) become pending, and until they are approved, runs use the previous definition. Approving or sending back is done by an approver on the product screen (it cannot be decided with the API).

Path Parameters​

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

Request Example​

Get definition approval
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
requiredbooleanWhether the tenant requires approval for definition changes
activeVersionnumber | nullNumber of the approved version of the definition (the one runs use)
pendingobject | nullThe pending change. null if there is none. Same fields as pending in Definition approval fields below, plus createdAt and changes
pending.createdAtstring | nullWhen the pending change was created (ISO 8601)
pending.changesarrayArray of what changes from the approved definition
pending.changes[].sectionstringKind of what changes. "project", "steps", "placements", "triggers", "notifications" or "connectors"
pending.changes[].keystring | nullWhich one within that kind (the ID of a step, placement or trigger, the ID of a connector, or the event and channel of a notification). null for "project"
pending.changes[].changestring"added", "removed" or "updated"
pending.changes[].fieldsarrayHint names of the changed fields. These names belong to this summary only and do not match the field names of the read responses. Check the content with a read using definition=pending
lastRejectionobject | nullThe last change that was sent back (null if a change was approved after it)
lastRejection.versionnumberNumber of the version that was sent back
lastRejection.reviewedByUserIdstring | nullUser ID of the person who sent it back
lastRejection.reviewedAtstring | nullWhen it was sent back (ISO 8601)
lastRejection.reasonstring | nullReason for sending it back
approverRulestringRule for who can approve (same as Definition approval fields below)
approversobjectPeople who can approve
approvers.ownerUserIdsarrayArray of the user IDs of the owners who can approve (excluding the requesters)
approvers.orgAdminCountnumberNumber of organization administrators who can approve
approvers.availablebooleanWhether there is someone who can approve it
canApprovebooleanWhether the caller can approve it (approval is done on the product screen)
canWithdrawbooleanWhether the caller can withdraw the pending change (owners)

Definition approval fields​

The fields of definitionApproval in the responses of the write APIs and of the API that withdraws a pending change.

FieldTypeDescription
requiredboolean | nullWhether the tenant requires approval for definition changes. null in the response of withdrawing a pending change when the setting could not be confirmed
statusstring"pending" (a change is pending) or "none" (nothing is pending)
activeVersionnumber | nullNumber of the approved version of the definition (the one runs use). null if there is none yet
pendingobject | nullThe pending change. null if there is none
pending.versionnumberNumber of the pending version
pending.digeststringValue of the pending change. Send it as pendingDigest when you withdraw the pending change (it differs from the digest of Get Project)
pending.baseVersionnumber | nullNumber of the version the pending change was based on
pending.initialbooleanWhether the first definition of a created project is pending. While true, runs cannot start
pending.requestedByUserIdsarrayArray of the user IDs of the people who requested the change (including those who laid further changes over the pending one)
pending.updatedAtstring | nullWhen the pending change last changed (ISO 8601)
pending.workItemIdstring | nullID of the approval request sent to the people who approve it (the ID of the Inbox row; it cannot be read with the review request API)
approverRulestringRule for who can approve. "owner_or_org_admin_not_requester" (an owner of the project or an administrator of the organization, other than the requester)
approversAvailablebooleanWhether there is someone who can approve it

Response Example​

JSON
{
"required": true,
"activeVersion": 2,
"pending": null,
"lastRejection": null,
"approverRule": "owner_or_org_admin_not_requester",
"approvers": {
"ownerUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"orgAdminCount": 1,
"available": true
},
"canApprove": false,
"canWithdraw": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not in UUID format
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409forbidden_roleCalled by a person with the organization operations role who does not take part in the project
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while

DELETE/v1/projects/{projectId}/definition-approval

Withdraws the definition change pending approval. Owners can call it. The pending change is discarded, and the approved definition stays.

Path Parameters​

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

Query Parameters​

パラメータ型必須説明
pendingDigeststring必須Value of the pending change to withdraw (pending.digest in the response of a write API or of this summary). It differs from the digest of Get Project

Request Example​

Withdraw definition approval
1curl -X DELETE "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/definition-approval?pendingDigest=c3d7b0e6e1840e4008c84b6e53e66bfc500453c3ff3a2a543d70374dc38b82d1" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
definitionApprovalobjectThe state after withdrawing (see Definition approval fields)

Response Example​

JSON
{
"definitionApproval": {
"required": true,
"status": "none",
"activeVersion": 2,
"pending": null,
"approverRule": "owner_or_org_admin_not_requester",
"approversAvailable": true
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not in UUID format, or pendingDigest is missing or malformed
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409no_pendingNothing is pending. Read the summary again before deciding
409approval_stalependingDigest differs from the current pending change (further changes were laid over it). Read the summary again before deciding
503definition_busyAnother change to the same definition is in progress. Retry after a while

Steps​

A step is a unit of the project's flow. There are steps run by Agents (defaultZone is "ai") and review steps decided by people ("gate"). There are also branch steps ("branch"; they hold no Agent) that choose the lane to go to from the result of the previous step. A project can have up to 12 steps. You cannot delete steps to leave fewer than the minimum (2 for a workflow, 1 for a cycle).

Endpoint List​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/stepsAdd a step
PATCH/v1/projects/{projectId}/steps/{stepId}Edit a step
PUT/v1/projects/{projectId}/steps/orderReorder steps
DELETE/v1/projects/{projectId}/steps/{stepId}Delete a step

Step Fields​

The fields of a step in steps of Get Project and in the responses of the step APIs.

FieldTypeDescription
stepIdstringStep ID (UUID)
positionnumber | nullPosition of the step (from 1)
namestring | nullStep name. When null, the screen shows a default name (such as "Step 1")
descriptionstring | nullDescription
enabledboolean | nullWhether it is enabled
defaultZonestring | nullOne of "ai" (run by an Agent), "gate" (review step) and "branch" (branch)
branchConfigobject | nullSettings of the branch (only for a step whose defaultZone is "branch"; null for other steps and for a branch step not yet set up). Also returned in the preview of a published project
branchConfig.lanes[]object[]Lanes: id, name (null for a lane without a name; optional when updating) and stepIds (the IDs of the steps in the lane, run from top to bottom)
branchConfig.rules[]object[]Conditions: id, kind (what to check and the kind of rule), the values for that kind, and to (where to go when it matches)
branchConfig.otherwiseobjectWhere to go when no condition matches
reworkToStepIdstring | nullID of the step to go back to when work is sent back (used by review steps)
gateConfigobject | nullSettings of a review step (the table below)
gateKindstring | nullKind of review: "review" (a person decides on the Agent's result) or "manual" (a person does the work and then proceeds)
scheduleobject | nullTime of the step (workflow only): expression (cron expression) and timezone
scheduleNextFireAtstring | nullWhen the step is next scheduled to run by its time (ISO 8601)
onDeniedstring | nullWhat happens "when it cannot run under the rules": "gate" (request a review) or "closed_failed" (close as failed). "goto" saved in an earlier version may be returned, but workflow runs request a review for it, as with "gate"
onDegradedstring | nullWhat happens "when the Agent reports a failure": "gate" (request a review). "proceed" or "goto" saved in an earlier version may be returned, but workflow runs request a review for them, as with "gate"
outcomeRoutesobject | nullAlways null (outcome routes cannot be set in the Marketplace edition)
laneIdstring | nullAlways null
placementExecutionstring | nullAlways null (runs them one at a time in placement order)
digeststringThe value to send as baseDigest when editing the step

Rules for branchConfig: add branchConfig with the API that updates a step, after adding the branch step (it cannot be sent with the API that adds a step). First, place the steps that make up the lanes right after the branch step, one lane after another. lanes holds 1 to 12 lanes (a project has up to 12 steps in all, including the branch step, so in practice up to 11), and every lane needs at least one step (a step cannot be in two lanes; name is up to 50 characters). rules are checked from the top, and the run goes to the to of the first matching condition (up to 8 conditions; with none, it always uses otherwise). to is {"kind": "lane", "laneId": …} or {"kind": "merge"} (join directly), and otherwise is either of those or {"kind": "ask"} (let a person choose); if omitted, it is merge. lanes[].id and rules[].id are up to 64 letters, digits, _ and -, and cannot repeat within the same settings. stepIds are step IDs (UUIDs). A branch step cannot be placed inside a lane, and a branch step and its lanes are placed outside parallel lanes.

Rule kinds (rules[].kind):

kindValuesMatches when
text_containsvalue (up to 200 characters; not whitespace only), negateThe result text of the previous step contains value (does not, when negate is true)
json_fieldpath (a dot-separated field name; up to 200 characters), op ("eq", "ne", "gte", "lte", "exists"), value (except for "exists"; a string of up to 200 characters, or a number)The field of the previous step's result JSON equals, differs from, is at least, or is at most value ("exists": the field is present)
files_existnegateThere are output files (there are none, when negate is true)
files_countop ("gte", "lte"), value (a whole number of 0 or more)The number of output files is at least or at most value
file_typefileType ("pdf", "excel", "word", "powerpoint", "image")There is an output file of that type
file_name_containsvalue (up to 200 characters; not whitespace only)An output file name contains value
duration_minutesop ("gte", "lte"), value (minutes; a whole number of 0 or more)The processing time of the previous step is at least or at most value minutes
send_backsop ("gte"), value (a whole number of 0 or more)The step was sent back at least value times
mutatingnegateWrite operations were made in the previous step (none were, when negate is true)
no_change_reported—The Agent reported that no changes were needed

An example body for the API that updates a step (two lanes: go to "Invoices" if there is a PDF output file, join directly if the result text contains "out of scope", and otherwise go to "Others"):

JSON
{
"baseDigest": "<the step's digest>",
"branchConfig": {
"lanes": [
{ "id": "lane-invoice", "name": "Invoices", "stepIds": ["3f6c1d2e-8b4a-4c1e-9f0a-1b2c3d4e5f60"] },
{ "id": "lane-other", "name": "Others", "stepIds": ["7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"] }
],
"rules": [
{ "id": "row-pdf", "kind": "file_type", "fileType": "pdf", "to": { "kind": "lane", "laneId": "lane-invoice" } },
{ "id": "row-skip", "kind": "text_contains", "value": "out of scope", "to": { "kind": "merge" } }
],
"otherwise": { "kind": "lane", "laneId": "lane-other" }
}
}

Settings of a review step (gateConfig):

FieldTypeDescription
approverUserIdsarrayArray of user IDs of the reviewers (up to 20 project members)
deadlineHoursnumber | nullReview deadline (hours; 1 to 720)
modestring | nullReview method. Only "blocking" (wait for the reviewer's decision) can be sent ("notify_only" returns 400 structure_not_for_marketplace). "notify_only" saved in an earlier version may be returned, but workflow runs always wait for the reviewer's decision regardless of the value
overdueActionstring | nullAfter the deadline. You can send "none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting) or null (works as "none") ("proceed", "send_back", and "reject" return 400 structure_not_for_marketplace). A value saved in an earlier version may be returned, but in workflow runs nothing is decided automatically after the deadline regardless of the value; the reviewers are notified and it keeps waiting
escalateToUserIdstring | nullUser ID of the contact when the deadline passes (a project member)
destinationsarrayNever included (destinations cannot be set in the Marketplace edition)

When a review step has no settings (gateConfig is null, or a field is missing), it works with mode "blocking", deadlineHours 24 hours, overdueAction "none", and no contact after the deadline. Sending null for deadlineHours, overdueAction, or escalateToUserId works the same (sending null for mode returns 400 Bad Request (invalid_parameter)). When gateKind is null, it is "review".

Depending on the type of the project, some settings cannot be set on steps.

Step settingworkflowcycle
Review steps ("gate" for defaultZone) and their settings (gateConfig and gateKind)Can be set400 (cycle_gate_not_allowed)
Branch steps ("branch" for defaultZone) and branchConfigCan be set400 (cycle_branch_not_allowed)
"gate" for onDenied and onDegradedCan be set400 (cycle_gate_not_allowed)
schedule (time of the step)Can be set400 (invalid_parameter)
reworkToStepId (step to send back to)Can be set400 (invalid_parameter)

For a cycle, schedule and reworkToStepId are rejected only when a value other than null is sent (null is accepted so that a step you got can be sent back as is). For a cycle, how often an Agent runs is decided by the sweep of the placement, not by the step.

POST/v1/projects/{projectId}/steps

Adds a step. Only owners can call this API.

Path Parameters​

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

Request Body​

FieldTypeRequiredDescription
namestring | null—Step name (up to 100 characters; an empty string or null means the default name; cannot be only whitespace)
descriptionstring | null—Description (up to 2000 characters; an empty string or null means no description)
defaultZonestring—One of "ai", "gate" and "branch". "ai" if omitted. null or an empty string cannot be sent
branchConfig——Cannot be sent (400 step_reference_on_create). After adding the step, place the lane steps after it, then set it with the API that updates a step
outputConfig——Cannot be sent (anything other than null is 400 output_config_invalid; null is the same as not sending it)
afterStepIdstring—Add the step after this step (the ID of a step of this project)
beforeStepIdstring—Add the step before this step (the ID of a step of this project). If both afterStepId and beforeStepId are specified, the step is added before this step. If both are omitted, the step is added at the end
gateConfigobject | null—Settings of a review step (same form as gateConfig in Step Fields). null means no settings

Request Example​

Create step
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "name": "Difference report",
6 "description": null,
7 "defaultZone": "ai",
8 "afterStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
9}'

Response (201 Created)​

FieldTypeDescription
stepobjectThe added step
stepsarrayAll steps after the addition (in order)
stepsDigeststringThe value for the order of the steps after the addition
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"step": {
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "Difference report",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
},
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "Difference check",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "Difference report",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
}
],
"stepsDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, afterStepId or beforeStepId is not a step of this project, a field has the wrong type, length, or value (including a whitespace-only name, and null or an empty string for defaultZone), or approvers or escalateToRef was sent in gateConfig (use approverUserIds and escalateToUserId)
400invalid_bodyThe body is malformed JSON or not a JSON object
400structure_not_for_marketplaceA review step setting that the Marketplace edition does not have was sent ("notify_only" or automatic processing after the deadline). error.param holds the name of the refused field (gateConfig.mode, and so on)
400step_reference_on_createdestinations was sent in gateConfig (including null or an empty array; destinations cannot be set in the Marketplace edition), or branchConfig was sent (error.param is branchConfig; after adding the step, place the lane steps after it, then set it with the API that edits the step)
400cycle_gate_not_allowedTried to add a review step to a cycle
400cycle_branch_not_allowedTried to add a branch step ("branch") to a cycle
400branch_step_settingsA field that cannot be used in a branch step was sent. Do not send that field (its name is in error.param)
400output_config_invalidoutputConfig was sent (not available in the Marketplace edition; null is the same as not sending it). error.param is outputConfig
400approver_not_memberA user who is not a member was specified as a reviewer
400approvers_requiredTried to add a review step without reviewers to an active workflow
400escalate_to_not_memberA user who is not a member was specified as the contact when the deadline passes
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409too_many_stepsThere are already 12 steps
409flow_structure_conflictConflicts with how branch steps are placed (the reason is in error.reason; see below the error table of the API that reorders steps)
413body_too_largeThe body exceeds 32 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PATCH/v1/projects/{projectId}/steps/{stepId}

Edits a step. Only the fields you send are changed. Only owners can call this API.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
stepIdstring必須Step ID (UUID)

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesThe digest of the step
namestring | null—Step name (up to 100 characters). An empty string or null resets it to the default name. Cannot be only whitespace
descriptionstring—Description (up to 2000 characters; cannot be an empty string, only whitespace, or null)
defaultZonestring—One of "ai", "gate" and "branch"
branchConfigobject | null—Settings of the branch (only for a step whose defaultZone is "branch"; see branchConfig in Step Fields and the rules below). Sending it replaces the whole setting; null removes it
outputConfig——Cannot be sent (anything other than null is 400 output_config_invalid; null is the same as not sending it, so null alone is 400 invalid_parameter for having no field to change)
enabledboolean—Whether it is enabled. In a cycle, when it is disabled the placements on the step take no new starts (starts already accepted are not cancelled), and when it is enabled again the placements that had sweeping enabled go back to their saved schedule
gateConfigobject | null—Settings of a review step. Only the fields you send are overlaid on the current values. null removes the settings. For a step that saved "notify_only" or automatic processing after the deadline in an earlier version, sending only other fields returns 400 (structure_not_for_marketplace). In that case, also send "blocking" for mode and "none" for overdueAction
gateKindstring | null—"review" or "manual"
reworkToStepIdstring | null—Step to send back to (a step before this step). null removes it
onDeniedstring | null—"gate" or "closed_failed" ("goto" returns 400 structure_not_for_marketplace). Even on a step that saved such a value in an earlier version, the request is not refused unless you send onDenied. Sending the retrieved value back as is returns 400
onDegradedstring | null—"gate" ("proceed" and "goto" return 400 structure_not_for_marketplace). Even on a step that saved such a value in an earlier version, the request is not refused unless you send onDegraded. Sending the retrieved value back as is returns 400
scheduleobject | null—Time of the step (workflow only): expression (a 5-field cron expression) and timezone (UTC if omitted). null removes it

Send at least one field besides baseDigest.

Turning a step into a branch step removes its review, time, destination options, outcome handling, send-back target and run-at-the-same-time settings. A step that holds Agents cannot be turned into a branch step.

For the first step, the time of the step starts a workflow run at that time only when the project has no enabled time trigger. For other steps, the workflow run waits until that time.

Changing the reviewers (approverUserIds) or the review method (mode) is recorded in the records (audit trail).

Request Example​

Update step
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok",
6 "name": "Amount check (tax included)"
7}'

Response (200 OK)​

FieldTypeDescription
stepobjectThe step after the edit (with a new digest)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"step": {
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check (tax included)",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "TqY6SuPTAr9He0NlMBKIRn7dBe_z651rRqQKNaluOgg"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or stepId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, name was set to only whitespace, description was set to an empty string, only whitespace, or null, null was sent for defaultZone or enabled, a field has the wrong type, length, or value, schedule or reworkToStepId was sent for a cycle, or approvers or escalateToRef was sent in gateConfig (use approverUserIds and escalateToUserId)
400invalid_bodyThe body is malformed JSON or not a JSON object
400structure_not_for_marketplaceA step structure that the Marketplace edition does not have was sent (outcome routes, destinations, "goto" for onDenied, "proceed" or "goto" for onDegraded, "notify_only", automatic processing after the deadline, and so on). error.param holds the name of the refused field (onDenied, onDegraded, gateConfig.mode, and so on)
400cycle_gate_not_allowedTried to make a step of a cycle a review step, or specified "gate" for onDenied or onDegraded
400cycle_route_not_allowed"goto" was specified for a step of a cycle
400cycle_branch_not_allowedTried to make a step of a cycle a branch step ("branch"), or sent branchConfig for a step of a cycle
400branch_step_settingsA field that cannot be used in a branch step was sent. Do not send that field (its name is in error.param)
400output_config_invalidoutputConfig was sent (not available in the Marketplace edition; null is the same as not sending it). error.param is outputConfig
400invalid_branch_configbranchConfig has a wrong shape or value (1 to 12 lanes with at least one step each, up to 8 conditions, the id format, the rule values and so on; see the rules above). To remove it, send null
400branch_config_not_allowedbranchConfig was sent for a step whose defaultZone is not "branch" (send null to remove it)
400invalid_branch_lanesThe steps in branchConfig.lanes are not placed right after the branch step, lane by lane in the order of lanes (another step is between them). Reorder the steps first, then retry
400branch_nestedTried to use a lane step of another branch step for this branch step or its lanes. Remove it from the lanes of the other branch step first, or use a step outside them
409branch_step_has_agentsTried to make a step with placed Agents a branch step. Remove the placements first
409branch_ai_not_supportedA rule of kind "ai" was sent (not available in the Marketplace edition). Use rules of other kinds
400approver_not_memberA user who is not a member was specified as a reviewer
400approvers_requiredIn an active workflow, an enabled review step would have no reviewers
400escalate_to_not_memberA user who is not a member was specified as the contact when the deadline passes
400invalid_send_back_stepThe step to send back to is not a step before this step
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedTried to change schedule from its saved value, but an administrator has not permitted scheduled run creation. Leaving schedule out, sending the same value or removing it with null is accepted
404step_not_foundThe step does not exist, or you are not a member of the project
409stale_baseThe step has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
409flow_structure_conflictConflicts with how branch steps are placed (the reason is in error.reason; see below the error table of the API that reorders steps)
413body_too_largeThe body exceeds 32 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PUT/v1/projects/{projectId}/steps/order

Reorders steps. Only owners can call this API.

Path Parameters​

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

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesstepsDigest from Get Project
stepIdsarrayYesThe IDs of all steps in the new order (no duplicates)

Request Example​

Reorder steps
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/order \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "6r94LWhMkQ54T1GkU_ntdq-ZfgpGyeGFyu4Gt32V9H0",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
8 "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
9 "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
10 ]
11}'

Response (200 OK)​

FieldTypeDescription
stepsarrayAll steps after reordering
stepsDigeststringThe value for the order of the steps after reordering
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 2,
"name": "Difference report",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "Rr9d0bvpTCflXsaBXF5SyOdTar-R-fu2HRnPB9P6H4w"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 3,
"name": "Difference check",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
}
],
"stepsDigest": "TQbgPozTGXVTzA52FXfg_NPAcQRj94bGXmyUVP-WTeo",
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, baseDigest is missing, empty, or not a string, or stepIds is not the order of all steps
400invalid_bodyThe body is malformed JSON or not a JSON object
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409stale_baseThe order of the steps has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
409flow_structure_conflictConflicts with how branch steps are placed (the reason is in error.reason; see below the error table of the API that reorders steps)
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

When a 409 (flow_structure_conflict) comes from how branch steps are placed, error.reason holds the reason: branch_nested (a branch step would be in a lane of another branch step), or route_into_branch_lane (a step outside a lane of a branch step would send back or route into that lane). The same applies to flow_structure_conflict from the APIs that add, update and delete a step.

DELETE/v1/projects/{projectId}/steps/{stepId}

Deletes a step. Only owners can call this API. Send-back targets, destinations, and trigger start steps that point to the step are removed, and the placements and sweeps on the step are also removed. A step used by past workflow runs or review requests is kept for the records (historyKept is true). When the deletion becomes pending approval (definitionApproval.status is "pending"), the step is not deleted until it is approved, even though deleted: true is returned; it stays in the default read.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
stepIdstring必須Step ID (UUID)

Request Example​

Delete step
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/steps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

FieldTypeDescription
stepIdstringID of the deleted step
deletedbooleanAlways true
historyKeptboolean | nullWhether the step was kept for the records. null when the deletion is pending approval (it is not deleted yet)
stepsarrayAll steps after the deletion
stepsDigeststringThe value for the order of the steps after the deletion
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"deleted": true,
"historyKept": false,
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "nRjiVRVlUJgih6HC6AXykF2OI1HY7jc87benbjalYok"
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "Difference check",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null,
"digest": "QA4q3JArx0JxCUP5Yy1q2koi6Ef9ti4uP7WFVrHs6_Q"
}
],
"stepsDigest": "OCkD5Kg3AClwepKwjLk5TZT1bwRFId09NV7SQKZOpL4",
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or stepId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404step_not_foundThe step does not exist, or you are not a member of the project
409min_stepsThere are only as many steps as the minimum (2 for a workflow, 1 for a cycle)
409flow_structure_conflictConflicts with how branch steps are placed (the reason is in error.reason; see below the error table of the API that reorders steps)
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

Placements​

A placement is a registered Agent (an Agent registered by an administrator) placed in steps of a project. The same Agent can be placed only once in a project, and one placement can have multiple steps (its steps). For a cycle, how often an Agent runs (its sweep) is decided per pair of placement and step.

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/placementsList placements
GET/v1/projects/{projectId}/placements/{placementId}Get a placement
GET/v1/projects/agent-candidatesList the registered Agents that can be placed
POST/v1/projects/{projectId}/placementsPlace an Agent
DELETE/v1/projects/{projectId}/placements/{placementId}Remove a placement
PUT/v1/projects/{projectId}/placements/{placementId}/stepsChange the steps of a placement
PUT/v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-configSet the runtime config of a placement for a step
PATCH/v1/projects/{projectId}/placements/{placementId}/scheduleStop, resume, or change the interval of a sweep (cycle only)

Placement Fields​

The fields of a placement in placements of Get Project and in the responses of the placement APIs.

FieldTypeDescription
placementIdstringPlacement ID (UUID)
agentIdstring | nullID of the placed Agent
displayOrdernumber | nullDisplay order
namestring | nullAgent name
descriptionstring | nullAgent description
goalstring | nullAlways null
guardrailstring | nullAlways null
skillsarrayAlways an empty array
skillCountnumber | nullAlways 0
playbookIdstring | nullAlways null
playbookNamestring | nullAlways null
inputFilesarrayAlways an empty array
stepIdsarrayArray of IDs of the steps of the placement
sweepsarraySweep settings (cycle): stepId, cron, timezone, and enabled for each step
runtimeConfigsarrayRuntime settings per step (stepId and runtimeConfig). runtimeConfig is returned in the form saved
libraryBindingsarrayAlways an empty array
memoryOrgIdstring | nullAlways null
memoryJobIdstring | nullAlways null
agentOwnerUserIdstring | nullUser ID of the owner of the placed Agent
isSharedboolean | nullWhether the placed Agent is shared
runtimeKindstring | nullKind of runtime of the Agent
marketplaceAgentIdstring | nullID of the registered Agent in the Marketplace edition. null otherwise
exclusiveToThisProjectboolean | nullWhether this project is the only project where this Agent is placed
agentStoppedboolean | nullWhether an administrator has stopped the placed Agent. While it is stopped, the steps of this placement do not start and wait for it to be resumed
relinkobject | nullAlways null
digeststringThe value to send as baseDigest to the APIs that change a placement (steps, sweep, and runtime config). It is made from the steps, runtime settings, and sweeps, and does not change when the Agent itself changes

GET/v1/projects/{projectId}/placements

Gets all placements of a project.

Query Parameters​

パラメータ型必須説明
definitionstring—With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition

Request Example​

List placements
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
placementsarrayArray of placements. See "Placement Fields" for the fields of an item
hasMorebooleanAlways false
definitionViewstring | nullOnly with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined

Response Example​

JSON
{
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409definition_invalidWith definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason)
503definition_busyWith definition=pending, another change to the same definition is in progress. Retry after a while

GET/v1/projects/{projectId}/placements/{placementId}

Gets one placement.

Query Parameters​

パラメータ型必須説明
definitionstring—With "pending", returns the view with the pending definition change laid over it. Without it, returns the approved definition

Request Example​

Get placement
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
placementobjectThe placement. See "Placement Fields" for the fields
definitionViewstring | nullOnly with definition=pending. "pending" (the view with the pending change laid over it) or "active" (nothing is pending). null for a person with the organization operations role who has not joined

Response Example​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or placementId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404placement_not_foundThe placement does not exist, it belongs to another project, or you are not a member of the project
409definition_invalidWith definition=pending, the definition would not be valid laid over the pending change (the kind of reason is in error.reason)
503definition_busyWith definition=pending, another change to the same definition is in progress. Retry after a while

GET/v1/projects/agent-candidates

Gets the registered Agents that can be placed in steps. Pass the returned marketplaceAgentId to the API that places a placement (POST /v1/projects/{projectId}/placements). All active registered Agents are returned in the order of their display names.

  • When project_type is "workflow", the registered Agents that have a workflow definition are returned. Only registered Agents whose certified is true can be placed in a workflow project.
  • When project_type is "cycle", all active registered Agents are returned (certified and certificationProblem are null).

For registered Agents that have a workflow definition, the definition needed to place and start them is also returned (input files, outputs, the shape and defaults of parameters, and connection slots). Upload input files with the API that uploads an input file and pass them in config when starting a workflow run. For candidates without a definition (candidates for "cycle" and workflow candidates whose definition cannot be read), these five fields are null (the fields are not omitted).

Query Parameters​

ParameterTypeDefaultDescription
project_typestring"workflow"The type of the project to place in: "workflow" or "cycle"

Request Example​

List agent candidates
1curl "https://<your-domain>/api/v1/projects/agent-candidates?project_type=workflow" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
candidatesarrayArray of registered Agents that can be placed
candidates[].marketplaceAgentIdstring | nullID of the registered Agent. Pass it to the API that places a placement
candidates[].displayNamestring | nullDisplay name
candidates[].descriptionstring | nullDescription
candidates[].iconUrlstring | nullURL of the icon
candidates[].tagsarrayArray of tags
candidates[].certifiedboolean | nullWhether the Agent is certified for use in workflows ("workflow" only)
candidates[].certificationProblemstring | nullCode of the reason why the Agent is not certified. null when it is certified, and for "cycle"
candidates[].inputsarray | nullInput files the registered Agent receives. Use the names in fileBindings of config when starting, and in inputBindings of the runtime config
candidates[].inputs[].namestring | nullName of the input file
candidates[].inputs[].formatstring | nullFormat ("markdown", "yaml", "json", "text", or "binary")
candidates[].inputs[].requiredbooleanWhether the input is required
candidates[].inputs[].editablebooleanWhether a person provides the content
candidates[].inputs[].fromParametersbooleanWhether the input is made from parameters
candidates[].inputs[].schemaobject | nullShape of a "yaml" or "json" input (JSON Schema). Uploaded files are checked against it
candidates[].outputsarray | nullOutput files the registered Agent makes (name, format, required). Use the names as output in inputBindings of later steps
candidates[].parametersSchemaobject | nullShape of parameters (JSON Schema)
candidates[].defaultsobject | nullDefault values of the definition
candidates[].connectionSlotsarray | nullConnection slots: name (slot name), required (whether required), and allowedProviderIds (array of the IDs of the connectors that can be specified)
hasMorebooleanAlways false (all candidates are returned)

Response Example​

JSON
{
"candidates": [
{
"marketplaceAgentId": "invoice-checker",
"displayName": "Invoice check",
"description": "Matches invoice amounts against line items",
"iconUrl": null,
"tags": [
"Accounting"
],
"certified": true,
"certificationProblem": null,
"inputs": [
{
"name": "invoice",
"format": "json",
"required": true,
"editable": false,
"fromParameters": false,
"schema": {
"type": "object"
}
}
],
"outputs": [
{
"name": "report",
"format": "markdown",
"required": true
}
],
"parametersSchema": {
"type": "object",
"properties": {
"currency": {
"type": "string"
}
}
},
"defaults": {
"currency": "JPY"
},
"connectionSlots": []
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterproject_type is neither "workflow" nor "cycle"
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server

POST/v1/projects/{projectId}/placements

Places a registered Agent in steps of a project. Only owners can call this API. Specify the registered Agent with the marketplaceAgentId of the Agent candidates (GET /v1/projects/agent-candidates).

Request Body​

FieldTypeRequiredDescription
marketplaceAgentIdstringYesID of the registered Agent to place (the marketplaceAgentId of the Agent candidates; 1 to 100 characters; leading and trailing spaces are removed)
stepIdsarray—Array of IDs of the steps of the placement (up to 12 steps of this project). If omitted, the Agent is placed without steps
  • If the same Agent is already placed, 409 Conflict (placement_already_exists) is returned. If the steps are also the same, the request is treated as a resend and the existing placement is returned. To change the steps, use the API that changes the steps of a placement.
  • agentId cannot be sent (sending it returns 400 Bad Request (invalid_parameter)).
  • A newly placed placement goes to the end of the placement order (displayOrder). However, placing the same Agent as a placement removed earlier (a placement kept because past workflow runs used it) brings that placement back with its original ID and position. When the placements of a step run one at a time, they run in this order. There is no API to reorder placements.

Request Example​

Place agent
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "marketplaceAgentId": "invoice-checker",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
8 ]
9}'

Response (201 Created)​

FieldTypeDescription
placementobjectThe placed placement. See "Placement Fields" for the fields
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, marketplaceAgentId is missing, empty, or longer than 100 characters, agentId was sent, or stepIds is invalid (more than 12, not steps of this project, the same step twice, and so on)
400invalid_bodyThe body is malformed JSON or not a JSON object
400agent_not_foundThe registered Agent in marketplaceAgentId does not exist or is not active
400agent_not_certifiedA registered Agent that is not certified for use in workflows was specified for a workflow project
400lanes_not_for_marketplaceA registered Agent was placed in a project that has lanes
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
409placement_already_existsThe same Agent is already placed (with different steps)
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

DELETE/v1/projects/{projectId}/placements/{placementId}

Removes a placement. Only owners can call this API. A placement used by past workflow runs is kept for the records (historyKept is true). When the removal becomes pending approval (definitionApproval.status is "pending"), the placement is not removed until it is approved, even though deleted: true is returned; it stays in the default read. Past executions of a removed placement remain in the execution history with the original placement ID (placementId).

Request Example​

Remove placement
1curl -X DELETE https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

FieldTypeDescription
placementIdstringID of the removed placement
deletedbooleanAlways true
historyKeptboolean | nullWhether the placement was kept for the records. null when the removal is pending approval (it is not removed yet)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"deleted": true,
"historyKept": false,
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or placementId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404placement_not_foundThe placement does not exist, it belongs to another project, or you are not a member of the project
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PUT/v1/projects/{projectId}/placements/{placementId}/steps

Replaces the steps of a placement with the steps you send. Only owners can call this API. The sweeps of the removed steps stop. An empty array can also be sent (the placement stays in the project, but it does not run because it has no steps).

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesThe digest of the placement
stepIdsarrayYesArray of IDs of the steps of the placement (up to 12 steps of this project)

Request Example​

Update placement steps
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "stepIds": [
7 "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
8 "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
9 ]
10}'

Response (200 OK)​

FieldTypeDescription
placementobjectThe placement after the change (with a new digest)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "T4llTd4mnzoQvxn2wLcaiiTARKxh9AMsregqNUhNaCg"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or placementId is not a UUID, baseDigest is missing, empty, or not a string, or stepIds is invalid (more than 12, not steps of this project, the same step twice, and so on)
400invalid_bodyThe body is malformed JSON or not a JSON object
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404placement_not_foundThe placement does not exist, it belongs to another project, or you are not a member of the project
409stale_baseThe placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PUT/v1/projects/{projectId}/placements/{placementId}/steps/{stepId}/runtime-config

Replaces the runtime config of one step of a placement with the content sent. Only owners of the project can call this API. For workflow, write the registered Agent's parameters, the connectors for its connection slots (connectionBindings), and which earlier step's output is passed to which input file (inputBindings). For cycle, write only environment variables (env). Sending none of the config fields clears the config of the step. The config is used from the next workflow run that is started for workflow, and from the next sweep that starts (including one started by firing a trigger) for cycle.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
placementIdstring必須Placement ID (UUID)
stepIdstring必須ID of a step the placement is assigned to (UUID)

Request Body​

FieldTypeRequiredDescription
baseDigeststringRequiredThe digest returned when getting the placement
parametersobject—workflow only. The registered Agent's parameters (in the shape of parametersSchema from the list of registered Agents that can be placed)
connectionBindingsobject—workflow only. Maps connection slot names (connectionSlots[].name) to connector IDs
inputBindingsobject—workflow only. Maps input file names (inputs[].name) to { "placementId", "output", "stepId" } (the placement of an earlier step, the name of its output (outputs[].name), and the step; stepId can be omitted)
envobject—cycle only. Maps environment variable names to values (strings). Up to 32

The body is limited to 16 KiB.

Request Example​

Update placement runtime config
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/steps/5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819/runtime-config \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "parameters": {
7 "currency": "JPY"
8 },
9 "connectionBindings": {},
10 "inputBindings": {
11 "invoice": {
12 "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
13 "output": "report"
14 }
15 }
16}'

Response (200 OK)​

FieldTypeDescription
placementobjectThe placement after the update (with the new digest). See "Placement Fields" for the fields
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": {
"parameters": {
"currency": "JPY"
},
"connection_bindings": {},
"input_bindings": {
"invoice": {
"project_agent_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"output": "report"
}
}
}
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "EjOdiFVd4xYReELiRIREoCHSrd35rG1a0RcKlyvS52s"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId, placementId, or stepId is not a UUID, baseDigest is missing, or a field that does not match the project type is sent (env for workflow; parameters, connectionBindings, or inputBindings for cycle; param names the field)
400invalid_runtime_configThe config does not match the registered Agent definition (message includes the first three reasons)
400runtime_not_allowedThe config cannot be set for this step of the placement (for example, the registered Agent has no definition)
400env_invalid, env_too_many, env_too_large, env_value_invalid, env_name_invalid, env_name_reserved, env_name_denied, env_secret_override, env_denied_config_invalidThe env for cycle cannot be accepted (malformed, too many (up to 32 names), too large (names and values up to 16KiB in total), a value is not a string, an invalid name, a reserved name, a name the administrator does not allow, a secret name of the registered Agent, or the administrator's rules cannot be read; message includes the name)
400invalid_bodyThe request body is malformed JSON or is not a JSON object
403forbiddenCalled with a system integration token
403owner_onlyThe caller is a member of the project but not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404placement_not_foundThe project or placement does not exist, the caller is not a member, or the placement is not assigned to the step
409stale_basebaseDigest differs from the current digest of the placement (get it again and resend). If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
413body_too_largeThe request body exceeds 16 KiB
415unsupported_media_typeA request body is sent with a Content-Type other than application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PATCH/v1/projects/{projectId}/placements/{placementId}/schedule

For a cycle project, stops, resumes, or changes the interval of the sweep of a placement. Only the fields you send are changed. Only owners can call this API.

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesThe digest of the placement
stepIdstring—ID of the step of the sweep (a step of the placement). Can be omitted for a placement with one step
enabledboolean—true sweeps and false stops. Even with true, it does not sweep while the step is disabled, the project is paused, an administrator has stopped the project or its Agent, or an administrator has suspended the person the project runs as (when the step is enabled again, or the project or Agent is resumed, it sweeps on the saved schedule)
cronstring—Interval (a 5-field cron expression; up to 100 characters)
timezonestring—Time zone (an IANA time zone name, up to 64 characters; for example, "Asia/Tokyo")
  • Send at least one of enabled, cron, and timezone. Fields you do not send keep their current values.
  • When the step has no sweep yet (setting it for the first time), cron is required. If enabled is omitted, the sweep stays stopped, and if timezone is omitted, UTC is used.

Request Example​

Update placement schedule
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/placements/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/schedule \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "dBhO2At8mWBO_6gCo9pEg6ehdL5oyZhZ4n6_FLYp3NU",
6 "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
7 "enabled": true,
8 "cron": "0 9 * * 1",
9 "timezone": "Asia/Tokyo"
10}'

Response (200 OK)​

FieldTypeDescription
placementobjectThe placement after the change (with a new digest)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Response Example​

JSON
{
"placement": {
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"displayOrder": 0,
"name": "Invoice check",
"description": "Matches invoice amounts against line items",
"goal": null,
"guardrail": null,
"skills": [],
"skillCount": 0,
"playbookId": null,
"playbookName": null,
"inputFiles": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
],
"sweeps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"enabled": true
}
],
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"memoryOrgId": null,
"memoryJobId": null,
"agentOwnerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"isShared": false,
"runtimeKind": "marketplace",
"marketplaceAgentId": "invoice-checker",
"exclusiveToThisProject": true,
"agentStopped": false,
"relink": null,
"digest": "TQwslacxj54G-mnF8xImeTexwswd53sGTRNesIiHwyU"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId, placementId, or stepId is not a UUID, baseDigest is missing, empty, or not a string, no fields to change, enabled, cron, or timezone has the wrong type, cron is not a valid cron expression or exceeds 100 characters, timezone is only whitespace, is not a valid time zone, or exceeds 64 characters, the project is a workflow, stepId is required but missing, or cron is missing when setting the sweep for the first time
400invalid_bodyThe body is malformed JSON or not a JSON object
400step_not_foundstepId is not a step of this placement
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedThe change leaves the sweep enabled while turning it on or changing the cron or timezone of an enabled sweep (fields you leave out keep their current values), but an administrator has not permitted scheduled run creation. Sending enabled false is accepted
404placement_not_foundThe placement does not exist, it belongs to another project, or you are not a member of the project
409stale_baseThe placement has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
409principalThe principal that runs the project (the current owner of the project) cannot be confirmed
409not_marketplaceThe placement is not of a registered Agent (only placements of registered Agents can have a schedule)
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

Triggers​

A trigger is what sets a project in motion. A time trigger ("cron") exists only in workflow projects and starts a workflow run at the times you set (a cycle runs at set times through each placement's patrol). A webhook trigger ("webhook") exists only in cycle projects; firing it runs the placement tied to the trigger once, as an extra run. Trigger IDs and their current settings can be read from triggers of Get Project.

Endpoint List​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/triggersCreate a trigger
PATCH/v1/projects/{projectId}/triggers/{triggerId}Change a trigger
DELETE/v1/projects/{projectId}/triggers/{triggerId}Delete a trigger
POST/v1/projects/{projectId}/triggers/{triggerId}/fireFire a trigger to run once as an extra run

POST/v1/projects/{projectId}/triggers

Creates a trigger. Only owners can call it. It cannot be called with a system integration token.

Path Parameters​

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

Request Body​

FieldTypeRequiredDescription
typestringYes"cron" (time, workflow only) or "webhook" (cycle only)
namestring | null—Name (up to 100 characters). Omit it or send null for no name
enabledboolean—Whether it is enabled. true if omitted. null cannot be sent
cronstringYes for "cron"A 5-field cron expression (minute hour day month weekday, e.g. "0 9 * * 1"). Up to 100 characters
timezonestring | null—Time zone of "cron" (an IANA name such as "Asia/Tokyo", up to 64 characters). UTC if omitted or null. An empty string cannot be sent
startStepIdstring | null—Step that "cron" starts from (the ID of a step of this project). From the first step if omitted or null
placementIdstringYes for "webhook"ID of the placement that a fire runs
stepIdstringYes for "webhook"ID of the step that a fire runs (a step of that placement)

Each type takes its own fields: "cron" takes name, enabled, cron, timezone, and startStepId; "webhook" takes name, enabled, placementId, and stepId. Sending a field of the other type returns 400 Bad Request (invalid_parameter, with that field in param).

Response (201 Created)​

FieldTypeDescription
triggerobjectThe created trigger, with the same fields as triggers[] of Get Project (including digest; startFailure of a new "cron" trigger is null)
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Request Example​

Create triggers
1curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "type": "cron",
6 "name": "Every Monday at 9:00",
7 "cron": "0 9 * * 1",
8 "timezone": "Asia/Tokyo"
9}'

Response Example​

JSON
{
"trigger": {
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"type": "cron",
"name": "Mondays at 9",
"enabled": true,
"lastFiredAt": null,
"nextFireAt": "2026-11-16T00:00:00.000Z",
"createdAt": "2026-11-10T09:00:00.000Z",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"startStepId": null,
"startFailure": null,
"digest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID; type is missing, null, or not "cron" or "webhook"; cron is missing for "cron"; placementId or stepId is missing for "webhook"; a field of the other type was sent; cron cannot be read or exceeds 100 characters; timezone is not an IANA name, is an empty string, or exceeds 64 characters; name exceeds 100 characters; startStepId, placementId, or stepId is not a UUID; enabled is not a boolean; startStepId is not a step of this project; or stepId is not a step of that placement
400invalid_bodyThe body is malformed JSON or not a JSON object
400webhook_cycle_onlyTried to create a "webhook" trigger in a project that is not a cycle (use "cron" for a workflow)
400cron_workflow_onlyTried to create a "cron" trigger in a cycle project (a cycle runs at set times through each placement's patrol)
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedAn administrator has not permitted scheduled run creation (checked whenever a trigger is created, whatever its type or enabled)
404project_not_foundThe project does not exist, or you are not a member
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

PATCH/v1/projects/{projectId}/triggers/{triggerId}

Changes a trigger. Only the fields you send are changed. Only owners can call it. It cannot be called with a system integration token.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
triggerIdstring必須Trigger ID (UUID; triggers[].triggerId of Get Project)

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesThe digest of the trigger (triggers[].digest of Get Project)
namestring—Name (up to 100 characters)
enabledboolean—Whether it is enabled
cronstring—A 5-field cron expression ("cron" only). Up to 100 characters
timezonestring—Time zone ("cron" only; an IANA name, up to 64 characters)
startStepIdstring—Step to start from ("cron" only; the ID of a step of this project)
placementIdstring—ID of the placement that a fire runs ("webhook" only)
stepIdstring—ID of the step that a fire runs ("webhook" only; a step of that placement)
  • Send at least one field besides baseDigest.
  • type cannot be changed (sending it returns 400 Bad Request). To change the type, delete the trigger and create another.
  • Fields cannot be cleared. Sending null, an empty string, or only whitespace returns 400 Bad Request.

Response (200 OK)​

FieldTypeDescription
triggerobjectThe trigger after the change (with a new digest), with the same fields as triggers[] of Get Project
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Request Example​

Update 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40
1curl -X PATCH https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "Nb8SAh4xIBu2F65clLazvr8vEGwTTPar7GdAw5jDKRA",
6 "enabled": false
7}'

Response Example​

JSON
{
"trigger": {
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"type": "cron",
"name": "Mondays at 9",
"enabled": false,
"lastFiredAt": null,
"nextFireAt": null,
"createdAt": "2026-11-10T09:00:00.000Z",
"cron": "0 9 * * 1",
"timezone": "Asia/Tokyo",
"startStepId": null,
"startFailure": null,
"digest": "hpCcTMyiZEFKOV5AE5g-Hszqkdf2P2HKL7AJz_s0RsU"
},
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or triggerId is not a UUID; baseDigest is missing, empty, or not a string; type was sent; no field to change was sent; null, an empty string, or only whitespace was sent for a field; a field not of the trigger's type was sent; a field has the wrong type, length, or value (as when creating); startStepId is not a step of this project; or stepId is not a step of that placement
400invalid_bodyThe body is malformed JSON or not a JSON object
400cron_workflow_onlyTried to change a "cron" trigger of a cycle project (it can be deleted)
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedTried to enable a disabled trigger (enabled set to true), but an administrator has not permitted scheduled run creation. Changes that do not enable it are accepted
404trigger_not_foundThe trigger does not exist or belongs to another project, or you are not a member of the project
409stale_baseThe trigger has changed since you got it. If a change is pending approval, the digest from the default read does not match; read again with definition=pending and send that digest as baseDigest
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503feature_permissions_unavailableThe feature permissions could not be checked. Retry after a while
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

DELETE/v1/projects/{projectId}/triggers/{triggerId}

Deletes a trigger. Only owners can call it. It cannot be called with a system integration token. When the deletion becomes pending approval (definitionApproval.status is "pending"), the trigger is not deleted until it is approved, even though deleted: true is returned; it stays in the default read.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
triggerIdstring必須Trigger ID (UUID)

Response (200 OK)​

FieldTypeDescription
triggerIdstringID of the deleted trigger
deletedbooleanAlways true
definitionApprovalobject | nullWhen the tenant requires approval for definition changes, this change becomes pending and this holds its state (status is "pending"; see Definition approval fields). Until it is approved, runs use the previous definition. null when no approval is required and the change took effect at once

Request Example​

Delete 8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40
1curl -X DELETE https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/triggers/8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40 \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"triggerId": "8d0f6a2e-4b1c-4e7a-9f3d-2c5b7a9e1f40",
"deleted": true,
"definitionApproval": null
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or triggerId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404trigger_not_foundThe trigger does not exist or belongs to another project, or you are not a member of the project
409definition_invalidLaid over the pending change, the definition would not be valid (the kind of reason is in error.reason). Read again with definition=pending and fix it by looking at the combined result
503approval_setting_unavailableThe definition approval setting cannot be confirmed. Retry after a while
503definition_busyAnother change to the same definition is in progress. Retry after a while

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. Each fire is accepted separately and is never merged into an earlier fire. Fires to the same step of the same agent placement are processed one at a time, in the order they were accepted.

Path Parameters​

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

Request Body​

パラメータ型必須説明
eventIdstring必須A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and _ . : @ + - only
payloadany—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

Request Example​

Fire trigger
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "eventId": "order-20261118-0001",
6 "payload": {
7 "orderId": "A-1024"
8 }
9}'

Response Fields (202 Accepted)​

FieldTypeDescription
resultstring"accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)
jobIdstringID of the receiving job. It is fixed per combination of agent placement and step: fires to the same combination return the same value (it does not change per fire). It cannot be used to get run status (GET /v1/projects/{projectId}/runs/{runId})
executionIdstringID of the accepted sweep execution. It can be used to get the result of the execution and to stop the sweep execution. A resend with the same eventId returns the same value (it can be missing from the response to a resend; then find the execution as described in Finding the Execution Started by a Fire). Until it starts (this can take about a minute, and longer when earlier fires to the same step of the same agent placement are waiting), getting the result of the execution returns 404 Not Found (execution_not_found)

Response Example​

JSON
{
"result": "accepted",
"jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40",
"executionId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}
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​

StatuscodeDescription
400invalid_event_ideventId is missing or has an invalid format
400invalid_parameterprojectId or triggerId is not a UUID
400invalid_bodyThe request body is malformed JSON or is not a JSON object
415unsupported_media_typeA request body is sent with a Content-Type other than application/json
404trigger_not_foundThe project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified
409trigger_disabledThe trigger is disabled
409project_not_activeThe project is not in a runnable state
409principal_suspendedAn administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409admin_stoppedAn administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it
409placement_unavailableThe target agent placement does not exist, or is not in a state that can run
409event_conflictThe same eventId was sent with a different payload
413body_too_largeThe request body exceeds 16 KiB
429queue_fullThe number of fires waiting to run on the same step of the same agent placement has reached the limit (20)

Finding the Execution Started by a Fire​

The executionId in the response of a fire is the ID of the sweep execution that the fire starts. You can read it with Get the Result of an Execution (GET /v1/projects/{projectId}/executions/{executionId}) (404 Not Found until it starts). The execution history (GET /v1/projects/{projectId}/executions) cannot be filtered by the jobId in the response of a fire. The jobId is the same for each combination of a placement and a step, so it cannot tell executions apart either. Each fire becomes a separate execution, and the executions of the same step of the same placement run one at a time. To find it in the execution history, filter by the placement of the trigger (placementId) and the time of the fire (from).

Webhooks​

A project webhook tells an https URL you choose when an event happens in the project. One webhook sends one event (event). A project can have up to 20. It is different from a webhook trigger (which is fired from outside to run the project).

  • Only owners can call these 5 APIs (for the list and the deliveries too, a member who is not an owner gets 403 Forbidden (owner_only)). They cannot be called with a system integration token.
  • secret is write-only and is not returned in any response (hasSecret in the response tells whether one is set). Replacing its value does not change digest. Use a random string of letters and digits only for secret.

Events​

eventSent when
gate_reachedA review request arrives
gate_due_soonThe deadline of a review request is near
gate_overdueA review request is past its deadline
run_deadline_overdueA workflow run is past its deadline
run_stalledA workflow run stays stopped
run_closedA workflow run ends

What Is Sent​

The following JSON is sent with POST.

FieldTypeDescription
eventstringThe event (a value in the table above)
project_idstringProject ID
run_idstring | nullID of the workflow run
workitem_idstring | nullID of the review request
occurred_atstringWhen the event happened (ISO 8601)
linkstring | nullURL to open on the screen
statusstringOnly for run_closed. How the workflow run ended ("closed_done", "closed_failed", "closed_rejected", or "cancelled")
  • Headers: Content-Type: application/json and X-Agentic-Star-Event (the event). When a secret is set, X-Agentic-Star-Signature: sha256=<signature> is also sent. The signature is the HMAC-SHA256 of the received body as is (its bytes) with secret, in hexadecimal. Compute the same on the receiving side and compare.
  • Returning 2xx within 10 seconds counts as delivered. On any other response (including redirects), a timeout, or a failed connection, it is sent again after 1, 5, and 30 minutes (up to 4 times including the first). The same event can arrive more than once.
  • Delivery results are kept for 30 days and can be read with List Deliveries.

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/webhooksList webhooks
POST/v1/projects/{projectId}/webhooksCreate a webhook
PATCH/v1/projects/{projectId}/webhooks/{webhookId}Change a webhook
DELETE/v1/projects/{projectId}/webhooks/{webhookId}Delete a webhook
GET/v1/projects/{projectId}/webhooks/{webhookId}/deliveriesList deliveries

GET/v1/projects/{projectId}/webhooks

Gets all webhooks of the project (in the order they were created). Only owners can call it.

Path Parameters​

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

Response (200 OK)​

FieldTypeDescription
webhooksarrayArray of webhooks
webhooks[].webhookIdstringWebhook ID
webhooks[].eventstring | nullEvent it sends
webhooks[].urlstring | nullDestination URL
webhooks[].enabledboolean | nullWhether it is enabled
webhooks[].hasSecretbooleanWhether a secret is set (the secret is not returned)
webhooks[].createdAtstring | nullCreation time (ISO 8601)
webhooks[].lastDeliveryobject | nullResult of the latest delivery (status, httpStatus, at). Deliveries waiting to be sent again are not included. null if there is none yet
webhooks[].digeststringThe value to send as baseDigest when changing the webhook
eventsstring[]Events that can be sent
hasMorebooleanAlways false (all webhooks are returned)

Request Example​

Get webhooks
1curl https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"webhooks": [
{
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": true,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
"digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
}
],
"events": ["gate_reached", "gate_due_soon", "gate_overdue", "run_deadline_overdue", "run_stalled", "run_closed"],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

POST/v1/projects/{projectId}/webhooks

Creates a webhook. Only owners can call it.

Path Parameters​

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

Request Body​

FieldTypeRequiredDescription
eventstringYesEvent to send (a value in "Events" above)
urlstringYesDestination URL (up to 2048 characters). https only, without a user name or password. The host name must resolve to a public address that can be reached from outside
secretstring | null—Value used for the signature (up to 256 characters). Omit it, or send null or an empty string, for no signature
enabledboolean—Whether it is enabled. true if omitted

Response (201 Created)​

FieldTypeDescription
webhookobjectThe created webhook, with the same fields as webhooks[] of the list (lastDelivery is null)

Request Example​

Create webhooks
1curl -X POST https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "event": "run_closed",
6 "url": "https://example.com/hooks/agentic-star",
7 "secret": "<secret>"
8}'

Response Example​

JSON
{
"webhook": {
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": true,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": null,
"digest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8"
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID; event or url is missing or null; event is not one of the values above; url is not a string, is only whitespace, or exceeds 2048 characters; secret is not a string or exceeds 256 characters; or enabled is not a boolean
400invalid_bodyThe body is malformed JSON or not a JSON object
400invalid_url_formaturl cannot be read as a URL
400https_requiredurl is not https, or contains a user name or password
400blocked_hostThe host of url cannot receive webhooks (a local, private, or internal address)
400unresolvable_hostThe host name of url could not be resolved
400too_many_webhooksThe project already has 20 webhooks
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json

PATCH/v1/projects/{projectId}/webhooks/{webhookId}

Changes a webhook. Only the fields you send are changed. Only owners can call it.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
webhookIdstring必須Webhook ID (UUID; webhooks[].webhookId of the list)

Request Body​

FieldTypeRequiredDescription
baseDigeststringYesThe digest of the webhook (webhooks[].digest of the list)
eventstring—Event to send
urlstring—Destination URL (the same rules as when creating)
secretstring | null—Value used for the signature (up to 256 characters). Replaced with the value you send. null or an empty string removes it
enabledboolean—Whether it is enabled
  • Send at least one field besides baseDigest.
  • event, url, and enabled cannot be cleared (sending null, an empty string, or only whitespace returns 400 Bad Request).

Response (200 OK)​

FieldTypeDescription
webhookobjectThe webhook after the change (with a new digest), with the same fields as webhooks[] of the list

Request Example​

Update c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a
1curl -X PATCH https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "baseDigest": "ZzMbbf4GuA4lERz6RWQYwm5-MIwi5DlFRdIX6Plzxb8",
6 "enabled": false
7}'

Response Example​

JSON
{
"webhook": {
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"event": "run_closed",
"url": "https://example.com/hooks/agentic-star",
"enabled": false,
"hasSecret": true,
"createdAt": "2026-11-10T09:00:00.000Z",
"lastDelivery": { "status": "delivered", "httpStatus": 200, "at": "2026-11-10T10:15:02.000Z" },
"digest": "p6lFz_URDGJlbWylUwuz5Y41RzkRw7p7AFwUZOr6hpk"
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or webhookId is not a UUID; baseDigest is missing, empty, or not a string; no field to change was sent; null, an empty string, or only whitespace was sent for event, url, or enabled; or a field has the wrong type, length, or value (as when creating)
400invalid_bodyThe body is malformed JSON or not a JSON object
400invalid_url_formaturl cannot be read as a URL
400https_requiredurl is not https, or contains a user name or password
400blocked_hostThe host of url cannot receive webhooks (a local, private, or internal address)
400unresolvable_hostThe host name of url could not be resolved
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404webhook_not_foundThe webhook does not exist or belongs to another project, or you are not a member of the project
409stale_baseThe webhook has changed since you got it
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json

DELETE/v1/projects/{projectId}/webhooks/{webhookId}

Deletes a webhook. Only owners can call it.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
webhookIdstring必須Webhook ID (UUID)

Response (200 OK)​

FieldTypeDescription
webhookIdstringID of the deleted webhook
deletedbooleanAlways true

Request Example​

Delete c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a
1curl -X DELETE https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"webhookId": "c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a",
"deleted": true
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or webhookId is not a UUID
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404webhook_not_foundThe webhook does not exist or belongs to another project, or you are not a member of the project

GET/v1/projects/{projectId}/webhooks/{webhookId}/deliveries

Gets the delivery results of a webhook, newest first (the last 30 days). The body that was sent is not returned. Only owners can call it.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
webhookIdstring必須Webhook ID (UUID)

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of items to fetch (1-100). There is no cursor

Response (200 OK)​

FieldTypeDescription
deliveriesarrayArray of delivery results (newest first)
deliveries[].deliveryIdstring | nullDelivery ID
deliveries[].eventstring | nullEvent
deliveries[].attemptnumber | nullWhich attempt this is
deliveries[].statusstring | null"delivered" (arrived), "pending" (not sent yet, or waiting to be sent again), or "failed" (did not arrive)
deliveries[].httpStatusnumber | nullHTTP status returned by the destination
deliveries[].atstring | nullTime of the result (ISO 8601)
deliveries[].nextAttemptAtstring | nullWhen it is to be sent again (ISO 8601)
deliveries[].lastErrorstring | nullWhy it did not arrive (e.g. "http_500", "timeout")
hasMorebooleanWhether there are older results than limit (when limit is 100, true when 100 items are returned)

Request Example​

Get deliveries
1curl "https://<your-domain>/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/webhooks/c6b1e2f4-7a3d-4c8e-9b5f-0d2a4e6c8b1a/deliveries?limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"deliveries": [
{
"deliveryId": "1042",
"event": "run_closed",
"attempt": 1,
"status": "delivered",
"httpStatus": 200,
"at": "2026-11-10T10:15:02.000Z",
"nextAttemptAt": null,
"lastError": null
},
{
"deliveryId": "1031",
"event": "run_closed",
"attempt": 4,
"status": "failed",
"httpStatus": 503,
"at": "2026-11-09T18:42:10.000Z",
"nextAttemptAt": null,
"lastError": "http_503"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or webhookId is not a UUID, or limit is not 1-100
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user record is not linked to an account of the authorization server
404webhook_not_foundThe webhook does not exist or belongs to another project, or you are not a member of the project

Workflow Runs​

A workflow run is one pass through the steps of a workflow project in order. Cycle projects do not create workflow runs (read cycle executions in the execution history).

Endpoint List​

メソッドエンドポイント説明
POST/v1/projects/{projectId}/runsStart a workflow run
GET/v1/projects/{projectId}/runs/{runId}Get a workflow run
GET/v1/projects/{projectId}/runsList workflow runs
GET/v1/projects/{projectId}/runs/{runId}/configGet the settings at the start of a workflow run
PATCH/v1/projects/{projectId}/runs/{runId}Set or clear the deadline of a workflow run
PUT/v1/projects/{projectId}/runs/{runId}/approversReassign the reviewers of a workflow run
POST/v1/projects/{projectId}/runs/{runId}/cancelCancel a workflow run
POST/v1/projects/{projectId}/artifactsUpload an input file (draft)
GET/v1/projects/{projectId}/artifactsList the artifacts of a workflow run
GET/v1/projects/{projectId}/artifacts/{artifactId}/contentGet the content of an artifact
GET/v1/projects/{projectId}/runs/{runId}/case-configGet the current case config of a workflow run
PUT/v1/projects/{projectId}/runs/{runId}/case-configReplace the case config of a workflow run waiting for review

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​

HeaderRequiredDescription
Idempotency-KeyRequiredA duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and _ . : - only

Path Parameters​

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

Request Body​

The body can be omitted. If you send one, make it a JSON object. Fields other than those below are ignored.

パラメータ型必須説明
payloadany—The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. The agent of the first step receives it in context.start_input (see "Request of a run started from outside" in the marketplace workflow guide). 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
configobject—Input files and step settings. Write one entry per placement and step, in the form { "placements": [{ "placementId", "stepId", "parameters", "connectionBindings", "fileBindings" }] }. fileBindings maps input file names (inputs[].name from the list of registered Agents that can be placed) to the artifactId of uploaded drafts; parameters are the registered Agent's parameters (in the shape of parametersSchema); connectionBindings maps connection slot names to connector IDs. All fields other than placementId and stepId can be omitted. Omitted or null means no settings

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.

config also counts toward the 16 KiB limit of the whole body.

Response Fields (201 Created / 200 OK)​

FieldTypeDescription
runIdstringRun ID (UUID). Use it to retrieve run status
existingboolean?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​

Start run
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
2-H "Authorization: Bearer <access_token>" \
3-H "Idempotency-Key: nightly-batch-20260917" \
4-H "Content-Type: application/json" \
5-d '{
6 "payload": {
7 "ticketId": "INC-1024",
8 "summary": "Some users cannot log in"
9 }
10}'

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.

Resending with the same key but a different payload or config returns 409 Conflict (origin_conflict).

Error Responses​

StatuscodeDescription
400idempotency_key_requiredThe Idempotency-Key header is missing
400idempotency_key_invalidThe Idempotency-Key length or character set is invalid
400invalid_parameterprojectId is not a UUID
400payload_too_largepayload exceeds 8,000 characters as a JSON string
400invalid_bodyThe request body is malformed JSON or is not a JSON object
413body_too_largeThe request body exceeds 16 KiB
415unsupported_media_typeA request body is sent with a Content-Type other than application/json
404project_not_foundThe project does not exist or is not accessible
400approvers_requiredAn enabled review step has no reviewers configured
409unsupported_project_typeA cycle project was specified
409project_inactiveThe project is not active (paused or archived)
409principal_suspendedAn administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension
409start_step_in_branch_laneThe 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
409definition_pendingThe 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
409relink_requiredThe 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. 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
409admin_stoppedAn administrator has stopped the project, or a registered agent placed in it. Ask an administrator to resume it (this API cannot resume it)
409mixed_runtimeRegistered agents and other agents are placed in the same project
409agent_not_certifiedA registered agent placed in the project is not certified for use in workflows
409lanes_not_for_marketplaceThe flow of the project has lanes (a project of registered agents cannot proceed with lanes)
400invalid_parameterA value in the start input is invalid
400missing_inputAn input file the step needs is missing (the previous step did not produce it, or it was not specified)
400duplicate_target_pathTwo or more input files would be placed at the same target path
400mp_placement_not_in_snapshotThe registered agent of the step is not in the configuration taken when the run started
400connection_version_missingThe connection version is not saved
400invalid_runtime_configThe runtime settings of the placement do not match the registered agent definition
400input_binding_cycleThe input bindings form a cycle
400input_binding_forward_referenceAn input refers to the output of a later step that has not run yet
400input_binding_unknown_outputAn output specified as an input does not exist in the source registered agent
400artifact_format_mismatchThe format of an artifact specified as an input differs from the required format
400artifact_digest_missingAn artifact specified as an input has no digest
400invalid_configconfig is malformed, names a placement or step that does not exist, does not match the registered Agent definition, or the project has no registered Agents placed on its steps
409artifact_not_readyAn artifact specified as an input is not ready yet (or differs from the content that was reviewed)
409origin_conflictA different payload or config was sent with the same Idempotency-Key (the same origin was already used with different content)
409connection_version_unavailableThe connection version cannot be confirmed (the connection target or permissions changed after approval)
429too_many_active_runsThe project already has the maximum number of runs (3 in total) that are running or awaiting review

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

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須Run ID (UUID)

Request Example​

Get run
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
runIdstringRun ID (UUID)
statusstringRun 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
originTypestring | nullHow the run started. One of "manual" (started from the UI), "api" (started through the API) or "cron" (scheduled)
originRefstring | nullA reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it
currentStepIdstring | nullID (UUID) of the step in progress. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain
startedByRefstring | nullWho or what started the run. See the "Who started the run" table below
actorLabelstring | nullDisplay name of a starter that is not a user (the service account name). null if unknown, and null otherwise
startedAtstring | nullStart time (ISO 8601). null before it starts
endedAtstring | nullEnd time (ISO 8601). null before it ends
summarystring | nullFor 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. null for a person with the organization operations role who does not take part in the project
runtimeKindstring | nullKind of runtime. "marketplace" (a run of registered agents) or "autonomous". May be null for older runs
cancelRequestedAtstring | nullTime (ISO 8601) when cancellation was requested. null if not requested
deadlineAtstring | nullDeadline of the workflow run (ISO 8601). null if it has no deadline
configRevisionnumber | nullRevision of the case configuration. Used by runs of registered agents; null for other runs. When you change the case config, use the revision you read with Get Run Case Config instead of this value (so that you do not overwrite a change made after you read it)
stepsarrayRecords of the step runs, in the order they were recorded
steps[].runStepIdstringID of the step run (starts with "rs:")
steps[].stepIdstring | nullStep ID (UUID)
steps[].placementIdstring | nullID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)
steps[].executionIdstring | nullID of the agent execution. Set once the agent starts running
steps[].conversationIdstring | nullID of the conversation of the agent execution. null for runs of registered agents
steps[].statusstringOne of "pending" (waiting to run), "running" (running), "waiting_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)
steps[].attemptnumber | nullRetry count within the same visit (starting at 1)
steps[].lanestring | nullAlways "main"
steps[].scheduledAtstring | nullWhen the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts
steps[].startedAtstring | nullStart time (ISO 8601)
steps[].endedAtstring | nullEnd time (ISO 8601)
steps[].outputSummarystring | nullSummary of the step output. null for a person with the organization operations role who does not take part in the project ("cancelled" for a step closed by cancellation is kept)
steps[].outcomestring | nullResult of the agent execution. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result
steps[].reasonCodestring | nullReason 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[].heldbooleanWhether the step is held because the project is paused and is waiting to resume
steps[].visitnumber | nullWhich visit to this step this is (increases with send-backs). null for rows without this record
steps[].reworkReasonstring | nullReason for the send-back
steps[].gateForstring | nullFor a review row, the step run (runStepId) it was raised for
steps[].routedFromstring | nullWhen steps were skipped by choosing a destination, the step run (runStepId) that chose it
steps[].latestring | nullWhy a result that arrived late was not used to advance the run
steps[].gateobject | nullSummary of the review. Set on review step rows. null for other rows
steps[].gate.decisionstring | nullOne of "proceed", "send_back" or "reject". null if not decided yet
steps[].gate.waitSourcestring | nullWhat the review waits for. "human" (a person's decision) or "external" (an external condition)
steps[].resumeCommandIdstring | nullAlways null
steps[].resumeReasonstring | nullAlways null
steps[].supersededBystring | nullAlways null
steps[].gateKindstring | nullAlways null
steps[].connectionConfirmOfstring | nullAlways null
plannedPlacementsarrayOrder of steps and placements planned to run, based on the configuration when the run started
plannedPlacements[].stepIdstring | nullStep ID (UUID)
plannedPlacements[].placementIdstring | nullPlacement ID (UUID). null for review steps and steps without an agent
lanesarrayAlways an empty array

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

Who started the run​
Started bystartedByRefactorLabel
A user (from the UI or the API)User IDnull
A service account"client:" followed by the client ID of the service accountName of the service account (null if unknown)
A schedulenullnull

For runs started by a service account before 2026-09-25, startedByRef is null.

Response Example​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "client:order-batch",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "marketplace",
"cancelRequestedAt": null,
"deadlineAt": null,
"configRevision": 1,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": null,
"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,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": 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​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID
404run_not_foundThe run does not exist, belongs to another project, or is not accessible

GET/v1/projects/{projectId}/runs

Lists workflow runs, newest start first. Up to the latest 100 are returned, and the next page (cursor) cannot be read. For a cycle project, the list is empty.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of items (1-100)
placement_idstring—Filter to workflow runs with steps handled by this placement (UUID)

Request Example​

List runs
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs?limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
runsarrayArray of workflow runs. The fields of an item are the same as Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId})
hasMorebooleanWhen limit is 99 or less, whether there are more. When limit is 100, true when 100 items are returned (there may be no more)

Workflow runs older than the latest 100 cannot be read with this list. Find the runId in the execution history (GET /v1/projects/{projectId}/executions, which supports the next page), and read it with Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}). Steps that have not started and steps waiting for a review do not appear in the execution history, so an old workflow run in which no step has started cannot be found.

Response Example​

JSON
{
"runs": [
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "client:order-batch",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "marketplace",
"cancelRequestedAt": null,
"deadlineAt": null,
"configRevision": 1,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": null,
"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,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": null
}
],
"plannedPlacements": [
{
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8"
},
{
"stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90",
"placementId": null
}
],
"lanes": []
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or placement_id is not a UUID, placement_id and placementId have different values, or limit is not an integer between 1 and 100
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

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

Gets the settings at the start of a workflow run (steps, placements, and connectors). These do not change even if the project's settings are changed later (only connectionId of the connectors is resolved from the current connector information).

Request Example​

Get run config
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/config \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
runIdstringID of the workflow run
takenAtstring | nullWhen the settings were copied (ISO 8601)
stepsarray | nullThe steps at that time. Same fields as Step Fields (without digest; fields not in the copy are null; for a branch step, branchConfig is included)
lanesarray | nullAll steps are in one "main" lane (name is null)
forksarray | nullAlways an empty array
joinsarray | nullAlways an empty array
placementsarray | nullThe placements at that time (placementId, agentId, name, goal, guardrail, skills, playbookId, playbookName, runtimeConfigs, libraryBindings, sweeps, and stepIds). runtimeConfigs and libraryBindings have the same form as the placement fields. goal, guardrail, skills, and playbookId are the values at the start. libraryBindings is always an empty array. goal, guardrail, playbookId, and playbookName are always null, and skills is always an empty array
connectorsarray | nullThe connectors at that time (kind, connectionId, name, and ledgerEnabled). name is the name at the start. connectionId is resolved from the current connector information (null if disabled or deleted in the admin console, or if it could not be checked)
sendBackLimitnumber | nullMaximum number of send-backs

For a workflow run without a copy of the settings, or whose copy cannot be read, everything other than runId is null.

Response Example​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"takenAt": "2026-09-17T01:30:00.000Z",
"steps": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 1,
"name": "Amount check",
"description": "Matches invoice amounts against line items",
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
},
{
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"position": 2,
"name": "Difference check",
"description": null,
"enabled": true,
"defaultZone": "gate",
"branchConfig": null,
"reworkToStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
},
{
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"position": 3,
"name": "Difference report",
"description": null,
"enabled": true,
"defaultZone": "ai",
"branchConfig": null,
"reworkToStepId": null,
"gateConfig": null,
"gateKind": null,
"schedule": null,
"scheduleNextFireAt": null,
"onDenied": null,
"onDegraded": null,
"outcomeRoutes": null,
"laneId": null,
"placementExecution": null
}
],
"lanes": [
{
"id": "main",
"name": null,
"parentLaneId": null,
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"
]
}
],
"forks": [],
"joins": [],
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
"name": "Invoice check",
"goal": null,
"guardrail": null,
"skills": [],
"playbookId": null,
"playbookName": null,
"runtimeConfigs": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"runtimeConfig": null
}
],
"libraryBindings": [],
"sweeps": [],
"stepIds": [
"5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819"
]
}
],
"connectors": [],
"sendBackLimit": 3
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404run_not_foundThe workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project

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

Sets or clears the deadline of a workflow run. When the deadline passes, a row for the workflow run past its deadline (run_deadline_overdue) appears in the queue. Owners and operators (including people with the organization operations role) can call this API. Only workflow runs that have not ended (status is "running" or "waiting_gate") can be changed.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須ID of the workflow run (UUID)

Request Body​

FieldTypeRequiredDescription
deadlineAtstring | nullYesDeadline (an ISO 8601 date-time in the future). null clears the deadline

Resending the same value gives the same result.

Request Example​

Set run deadline
1curl -X PATCH https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "deadlineAt": "2026-11-20T09:00:00.000Z"
6}'

Response Fields (200 OK)​

The workflow run after the change. The fields are the same as Get a Workflow Run (GET /v1/projects/{projectId}/runs/{runId}).

If reading the workflow run back after changing the deadline fails, 502 Bad Gateway (upstream_connection_error) is returned. The deadline may already have changed, so check deadlineAt with Get a Workflow Run before resending.

Response Example​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "running",
"originType": "api",
"originRef": "nightly-batch-20260917",
"currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"startedByRef": "client:order-batch",
"actorLabel": null,
"startedAt": "2026-09-17T01:30:00.000Z",
"endedAt": null,
"summary": null,
"runtimeKind": "marketplace",
"cancelRequestedAt": null,
"deadlineAt": "2026-11-20T09:00:00.000Z",
"configRevision": 1,
"steps": [
{
"runStepId": "rs:1042",
"stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
"placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"conversationId": null,
"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,
"resumeCommandId": null,
"resumeReason": null,
"supersededBy": null,
"gateKind": null,
"connectionConfirmOf": 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​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID, or deadlineAt is missing, is not an ISO 8601 date-time, or is not in the future
400invalid_bodyThe body is malformed JSON or not a JSON object
403forbiddenCalled with a system integration token
403operator_onlyA member who is neither an owner nor an operator and does not have the organization operations role
403sso_requiredThe user record is not linked to an account of the authorization server
404run_not_foundThe workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project
409invalid_stateThe workflow run has ended
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json
502upstream_connection_errorReading the workflow run back after changing the deadline failed (check with Get a Workflow Run before resending)

PUT/v1/projects/{projectId}/runs/{runId}/approvers

Replaces, all at once, the reviewers of the review requests of a workflow run that have not been decided yet. Owners and operators (including people with the organization operations role) can call this API. Only workflow runs that have not ended can be changed. The review request notification is sent only to people who newly become reviewers.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須ID of the workflow run (UUID)

Request Body​

FieldTypeRequiredDescription
approverUserIdsarrayYesUser IDs of the new reviewers (1 to 50 people; current members of the project only; up to 128 characters each; each person only once)
commandIdstringYesA value to identify resends (8 to 128 characters of letters, digits, and _ . : -)
  • If you resend the same reviewers with the same commandId, the same result as the first request is returned. Sending different reviewers with the same commandId returns 409 Conflict (command_conflict).
  • For a reassignment with very many reviewers or target review requests (for example, 50 reviewers), a resend with the same commandId cannot compare the reviewers, so 200 is returned as the result of the first request and workItemIds may be empty. Check the result with Get a Workflow Run and Get a Review Request.

Request Example​

Reassign run approvers
1curl -X PUT https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/approvers \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "approverUserIds": [
6 "f47ac10b-58cc-4372-a567-0e02b2c3d479"
7 ],
8 "commandId": "reassign-20261118-0001"
9}'

Response Fields (200 OK)​

FieldTypeDescription
runIdstringID of the workflow run
approverUserIdsarrayUser IDs of the reviewers after the change (the values you sent)
workItemIdsarrayIDs of the review requests whose reviewers were replaced

Response Example​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"workItemIds": [
"c9d8e7f6-a5b4-4321-8fed-cba098765432"
]
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID, approverUserIds is not an array of 1 to 50 user IDs (including an empty ID or an ID longer than 128 characters) or contains the same person twice, or commandId is missing or has the wrong form
400invalid_bodyThe body is malformed JSON or not a JSON object
400approver_not_memberapproverUserIds includes someone who is not a current member of the project
403forbiddenCalled with a system integration token
403operator_onlyA member who is neither an owner nor an operator and does not have the organization operations role
403sso_requiredThe user record is not linked to an account of the authorization server
404run_not_foundThe workflow run does not exist, belongs to another project, the project is a cycle, or you are not a member of the project
409invalid_stateThe workflow run has ended
409command_conflictDifferent reviewers were sent with the same commandId
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json

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. Owners and operators (including people with the organization operations role), and the person who started the workflow run, can call this API. It can also be called with a system integration token.

When it is cancelled:

  • The status of the workflow run becomes "cancelled" (cancelled). This cannot be undone.
  • Steps that have not started are not started. The Agents of running steps are told to stop (the status of such a step row may not change until it stops).
  • Review requests of review steps that have not been decided are withdrawn.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須ID of the workflow run (UUID)

Request Body​

FieldTypeRequiredDescription
commandIdstringYesA value to identify resends (8 to 128 characters of letters, digits, and _ . : -)
reasonstring—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.

Request Example​

Cancel run
1curl -X POST https://<your-domain>/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}'

Response Fields (202 Accepted / 200 OK)​

202 Accepted when this request cancelled the workflow run, and 200 OK when it did not.

FieldTypeDescription
runIdstringID of the workflow run
statusstringThe status of the workflow run after the request ("cancelled" when it was cancelled)
cancelRequestedAtstring | nullWhen the cancel was accepted (ISO 8601). null for a workflow run that was not cancelled
existingbooleantrue when this request did not newly cancel the workflow run (always false with 202 Accepted)

Response Example​

JSON
{
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"status": "cancelled",
"cancelRequestedAt": "2026-11-18T05:12:30.000Z",
"existing": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not a UUID, commandId is missing or has the wrong form, or reason is not a string or is longer than 500 characters
400invalid_bodyThe body is malformed JSON or not a JSON object
403operator_onlyA member who is neither an owner nor an operator and does not have the organization operations role tried to cancel a workflow run they did not start
403sso_requiredThe user record is not linked to an account of the authorization server
404run_not_foundThe workflow run does not exist, belongs to another project, or you are not a member of the project
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeThe Content-Type of the body is not application/json

GET/v1/projects/{projectId}/runs/{runId}/case-config

Gets the current case config of a workflow run that runs on registered Agents (the input files, parameters, and connections for each pair of placement and step). Any member of the project and people with the organization operations role can call it, whatever the state of the run. Before you change the case config, read the current config and its revision with this API.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須Workflow run ID (UUID)

Response Fields (200 OK)​

FieldTypeDescription
revisionnumber | nullThe version of the case config. Send it as expectedRevision when you change the case config. null for a run that does not run on registered Agents
placementsarrayThe config for each pair of placement and step. The fields are the same as config.placements in Start Workflow Run (placementId, stepId, parameters, connectionBindings, and fileBindings). Pairs with no config are also returned, with only placementId and stepId

Request Example​

Get case-config
1curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"revision": 2,
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"parameters": { "language": "en" },
"fileBindings": { "contract": "9b2f0c1e-3a4d-4e5f-8a6b-7c8d9e0f1a2b" }
},
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90"
}
]
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not in UUID format
403forbiddenCalled with a system integration token
403sso_requiredThe user is not linked to an account of the authentication server
404run_not_foundThe workflow run does not exist, belongs to another project, is of a cycle project, or the caller is not a member of the project

PUT/v1/projects/{projectId}/runs/{runId}/case-config

Replaces the whole case config of a workflow run that runs on registered Agents, while the run is waiting for review (status is "waiting_gate"). Only an owner can call it.

  • The config.placements you send replaces the whole config. The config of pairs of placement and step that you do not send is removed. Get the case config, change only what you want, and send all of it. Sending an empty array removes the whole config.
  • For expectedRevision, send the revision you read with Get Run Case Config. If you use configRevision from Get Workflow Run, you may overwrite a change made after you read it with an older config.
  • The changed config is used from the steps started after the work item is decided. A change also changes contextVersion and the basis of the decision of the work item waiting for review, so read the work item again before you decide (gate in the response has the new values).

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
runIdstring必須Workflow run ID (UUID)

Request Body​

FieldTypeRequiredDescription
expectedRevisionnumberRequiredThe revision you read with Get Run Case Config (an integer of 1 or more). 409 Conflict (revision_conflict) if it differs from the current version
commandIdstringRequiredA value that identifies a resend (8 to 128 characters of letters, digits, and _ . : -)
configobjectRequiredThe new case config, in the form { "placements": [...] }. placements is a required array. The fields of each pair of placement and step are the same as config in Start Workflow Run
  • Limits: config as JSON can be up to 262,144 characters (beyond that, 400 Bad Request (invalid_config)). A body over 787,456 bytes gives 413 Payload Too Large (body_too_large).
  • A resend with the same commandId and the same content returns the result of the first request (existing is true). The same commandId with different content gives 409 Conflict (command_conflict).

Response Fields (200 OK)​

FieldTypeDescription
revisionnumberThe version of the case config after the replacement
placementsarrayThe config after the replacement. The fields are the same as in Get Run Case Config
gateobject | nullThe work item waiting for review (workItemId, contextVersion, and basisDigest). When you decide, use this contextVersion and basisDigest, or the values from getting the work item again. null if there is none
existingbooleantrue when a resend with the same commandId returned the result of the first request

Request Example​

Replace case-config
1curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/case-config \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "expectedRevision": 2,
6 "commandId": "fix-contract-20261110-01",
7 "config": {
8 "placements": [
9 {
10 "placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
11 "stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
12 "parameters": {
13 "language": "ja"
14 },
15 "fileBindings": {
16 "contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6"
17 }
18 }
19 ]
20 }
21}'

Response Example​

JSON
{
"revision": 3,
"placements": [
{
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"parameters": { "language": "en" },
"fileBindings": { "contract": "8d1e2f3a-4b5c-4d6e-9f70-a1b2c3d4e5f6" }
}
],
"gate": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"contextVersion": 4,
"basisDigest": "5e0f6c9a3b2d1e4f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f"
},
"existing": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or runId is not in UUID format, expectedRevision is not an integer of 1 or more, or commandId is missing or malformed
400invalid_bodyThe body is malformed JSON or not a JSON object
400invalid_configconfig is missing or placements is not an array, it names a placement or step that does not exist, it does not match the registered Agent definition, or config is longer than 262,144 characters
400not_marketplace_runThe workflow run does not run on registered Agents
400connection_not_allowedA connection that is not a connection of the project was specified
400artifact_format_mismatchThe format of an artifact specified as an input differs from the required format
400artifact_digest_missingAn artifact specified as an input has no digest
400artifact_not_readyAn artifact specified as an input does not exist, belongs to another workflow run, or is not ready yet
403forbiddenCalled with a system integration token
403owner_onlyA member who is not an owner
403sso_requiredThe user is not linked to an account of the authentication server
404run_not_foundThe workflow run does not exist, belongs to another project, is of a cycle project, or the caller is not a member of the project
409run_runningThe workflow run is not waiting for review (get the workflow run again to check its state)
409run_closedThe workflow run has ended
409revision_conflictThe case config has changed since you read it. Get the case config again and send its revision as expectedRevision
409command_conflictDifferent content was sent with the same commandId
409connection_version_unavailableThe connection version cannot be confirmed. Check the connections of the project and resend
413body_too_largeThe body exceeds 787,456 bytes
415unsupported_media_typeThe Content-Type of the body is not application/json

POST/v1/projects/{projectId}/artifacts

Uploads an input file to pass to a workflow run, as a draft. Project participants (owners, operators and members) and people with the organization operations role can call this API. When you specify the artifactId of an uploaded draft in fileBindings of config when starting a workflow run (POST /v1/projects/{projectId}/runs), the draft becomes an artifact of that run and can be read with the APIs that list artifacts and get the content of an artifact. Until it is bound to a run, the content cannot be read through the external API (getting the content returns 404 Not Found). When a workflow run is started with a system integration token, only drafts that a current owner of the project uploaded, that are not yet bound to a run, and that are fully written can be specified.

Request Headers​

HeaderRequiredDescription
Idempotency-KeyOptionalKey to prevent duplicate uploads. 8-128 characters using alphanumerics and _ . : - only. Resending the same name, format, and content with the same key returns the same draft (200 OK)

Path Parameters​

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

Request Body (multipart/form-data)​

パラメータ型必須説明
filesfile必須File to upload. Exactly one
namestring必須Name of the input file (1-128 characters). inputs[].name from the list of registered Agents that can be placed
formatstring必須Format: one of "markdown", "yaml", "json", "text", "binary". inputs[].format from the list of registered Agents that can be placed

The size limit is 20 MiB for "binary" and 1 MiB for the other formats. Larger files return 413 Payload Too Large (file_too_large). "yaml" and "json" files are checked for whether they can be parsed and whether they match the definition (inputs[].schema) of the registered Agents placed in the project.

Request Example​

Upload draft artifact
1curl -X POST https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts \
2-H "Authorization: Bearer <access_token>" \
3-F "files=@invoice.json" \
4-F "name=invoice" \
5-F "format=json"

Response Fields (201 Created / 200 OK)​

Same shape as one item of the artifact list.

FieldTypeDescription
artifactIdstringID of the draft (UUID). Specify it in fileBindings of config when starting
runIdstring | nullnull for a draft
namestring | nullName of the artifact
mimeTypestring | nullMIME type of the artifact
sizenumber | nullSize (bytes)
statusstring | null"ready"
createdAtstring | nullWhen the artifact was made (ISO 8601)

A new upload returns 201 Created; resending the same draft with the same Idempotency-Key returns 200 OK.

Response Example​

JSON
{
"artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"runId": null,
"name": "invoice",
"mimeType": "application/json",
"size": 512,
"status": "ready",
"createdAt": "2026-11-18T05:20:00.000Z"
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, no file or more than one file is sent, name is missing or longer than 128 characters, or format is not one of the allowed values (param names the field)
400idempotency_key_invalidThe Idempotency-Key length or character set is invalid (the key is optional, but if sent it must be valid)
400invalid_yamlformat is "yaml" and the content cannot be parsed as YAML
400invalid_jsonformat is "json" and the content cannot be parsed as JSON
400schema_violationThe content does not match the input definition (inputs[].schema) of the placed registered Agent
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
403feature_not_permittedAn administrator has not permitted file uploads
404project_not_foundThe project does not exist, or the caller is not a member
409artifact_conflictA different name, format, or content was sent with the same Idempotency-Key, or the draft is already bound to a run
413file_too_largeThe file exceeds the limit (20 MiB for "binary", 1 MiB for the others)
415unsupported_media_typeThe request is not multipart/form-data
503feature_permissions_unavailableFeature permissions could not be checked (wait and retry)

GET/v1/projects/{projectId}/artifacts

Gets all artifacts of a workflow run (the input files bound at the start and the outputs made by the steps), in the order they were made. Read the content with the API that gets the content of an artifact (GET /v1/projects/{projectId}/artifacts/{artifactId}/content). Only members of the project can read them.

Path Parameters​

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

Query Parameters​

ParameterTypeDefaultDescription
run_idstring—Required. ID of the workflow run (UUID)

Request Example​

List run artifacts
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts?run_id=7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
artifactsarrayArray of artifacts
artifacts[].artifactIdstring | nullArtifact ID (UUID)
artifacts[].runIdstring | nullID of the workflow run
artifacts[].namestring | nullName of the artifact
artifacts[].mimeTypestring | nullMIME type of the artifact
artifacts[].sizenumber | nullSize (bytes)
artifacts[].statusstring | null"ready" (readable) or "uploading" (not fully written yet)
artifacts[].createdAtstring | nullWhen the artifact was made (ISO 8601)
hasMorebooleanAlways false (all artifacts are returned)

Response Example​

JSON
{
"artifacts": [
{
"artifactId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"name": "report.md",
"mimeType": "text/markdown",
"size": 2048,
"status": "ready",
"createdAt": "2026-11-18T05:30:00.000Z"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or run_id is missing or not a UUID
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
404run_not_foundThe workflow run does not exist, or belongs to another project

GET/v1/projects/{projectId}/artifacts/{artifactId}/content

Gets the content of an artifact. You can also call it with HEAD. The same headers are returned without the body, so you can check the size first. Reading it with GET leaves a view (forensic.viewed) in the records (audit trail) (HEAD does not).

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
artifactIdstring必須Artifact ID (UUID). The artifactId in the list of artifacts

Request Example​

Get run artifact content
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/artifacts/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/content \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

The content of the artifact is returned as it is.

Response headerDescription
Content-TypeMIME type of the artifact
Content-LengthSize (bytes)
X-Content-Type-Options"nosniff"
Content-Disposition"attachment" (returned as a download)

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or artifactId is not a UUID
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member
404artifact_not_foundThe artifact does not exist, belongs to another project, or is not an artifact of a workflow run
409forbidden_roleCalled by a person with the organization operations role who does not take part in the project
409artifact_not_readyThe artifact is not fully written yet

Executions​

An execution is one run of an Agent. Executions are listed in the execution history on the screen, and opening one shows the run record (when sweeps that changed nothing continue, the screen shows them as one row; this API returns them one by one without grouping). There are executions of workflow steps (kind is "run_step"; executionId has the form rs:<number>) and executions of cycle sweeps ("sweep"; executionId is a UUID).

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/executionsGet the execution history
GET/v1/projects/{projectId}/executions/{executionId}Get the result of an execution
GET/v1/projects/{projectId}/executions/{executionId}/operationsGet the list of tool calls
GET/v1/projects/{projectId}/executions/{executionId}/timelineGet the timeline of an execution
POST/v1/projects/{projectId}/executions/{executionId}/cancelStop a sweep execution of a cycle project

Outcome Values​

The values of outcome. For what the screen shows, see the Results Reference.

ValueShown on the screen
completedCompleted
incompleteFailed (reported by agent)
failedFailed
timeoutTimed out
stoppedFailed (stopped)
deniedNot allowed by rules
skippedNothing to do

For executions that have not finished, and executions that finished without a recorded result (insufficient records), outcome is null.

GET/v1/projects/{projectId}/executions

Gets the execution history, newest start time first. Cursor-based pagination is supported. Steps that have not started and steps waiting for a review are not included.

Query Parameters​

ParameterTypeDefaultDescription
fromstring—Filter to executions that started at or after this time (ISO 8601)
tostring—Filter to executions that started at or before this time (ISO 8601)
placement_idstring—Filter to executions of this placement (UUID)
step_idstring—Filter to executions of this step (UUID)
run_idstring—Filter to step executions of this workflow run (UUID)
outcomestring"all"Filter by result. Besides the outcome values: "all" (all), "success" (completed), "problems" (incomplete, failed, timeout, stopped, and denied), "running" (running), "missing" (insufficient records), or "unmeasured" (finished in a way where completion is not measured)
fix_targetstring—Filter by fix target: "goal", "skill", "handoff", "not_assigned", "connection", "rule", "guardrail", "external", or "unknown" (the values of envelope.completionReport.fixTarget in the execution result), or "platform" (executions with a platform-side failure)
reason_codestring—Filter to executions whose reason for the outcome (executions[].reasonCode) matches. Case-sensitive. Starts with a letter and contains only letters, digits, and _ . : -, up to 64 characters (surrounding whitespace is removed; no filter when empty)
qstring—Filter by part of the Agent name, the execution UUID, or the conversation ID (up to 200 characters). Cycle executions can be found by executionId. Workflow step executions cannot be found by rs:<number>; use steps[].executionId (a UUID) of the workflow run
limitinteger50Number of items per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Request Example​

List executions
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions?outcome=success&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
executionsarrayArray of executions
executions[].executionIdstringExecution ID. rs:<number> for a workflow, and a UUID for a cycle
executions[].kindstring | null"run_step" (a workflow step) or "sweep" (a cycle sweep)
executions[].runIdstring | nullID of the workflow run. null for a cycle
executions[].stepIdstring | nullStep ID
executions[].stepNamestring | nullStep name
executions[].stepPositionnumber | nullPosition of the step
executions[].placementIdstring | nullPlacement ID
executions[].agentNamestring | nullAgent name
executions[].attemptnumber | nullAttempt number (increases when a platform failure is retried. For a cycle, a relaunch is a new execution, and it does not increase)
executions[].lanestring | nullLane ID (workflow; "main" when there are no lanes)
executions[].outcomestring | nullOutcome (see "Outcome Values" above)
executions[].reasonCodestring | nullReason for the outcome. For a cycle, the reason the execution ended (for example, "guardrail_blocked"); for a workflow, the reason reported by the step
executions[].resultStatestring | null"terminal" (has a result), "running" (running), "missing" (insufficient record), "unmeasured" (completion not measured), or "not_applicable" (a row that is not an Agent execution, such as a review step)
executions[].terminalboolean | nullWhether it has finished
executions[].startedAtstring | nullStart time (ISO 8601)
executions[].endedAtstring | nullEnd time (ISO 8601)
executions[].summarystring | nullFinal response of a workflow step (up to 2000 characters). null for a cycle (read it in the execution result). null for a person with the organization operations role who does not take part in the project
executions[].errorMessagestring | nullError message (cycle)
executions[].originTypestring | nullHow it started. For a workflow, how the workflow run started ("manual", "api", or "cron"); for a cycle, "cron" (sweep) or "webhook" (trigger fire)
executions[].actorLabelstring | nullDisplay name of a starter that is not a user (the name of the service account)
executions[].gateDecisionstring | nullDecision of the review step
executions[].conversationIdstring | nullID of the execution conversation (used to read the execution conversation)
executions[].fixTargetstring | nullFix target (same values as envelope.completionReport.fixTarget in the execution result). null when absent
executions[].platformFailurestring | nullKind of platform-side failure (same values as envelope.platformFailure in the execution result). null when absent
executions[].rerunOfstring | nullAlways null
hasMorebooleanWhether there is a next page
cursorstringCursor for the next page. Included only when hasMore is true

Response Example​

JSON
{
"executions": [
{
"executionId": "rs:1842",
"kind": "run_step",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"stepName": "Amount check",
"stepPosition": 2,
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentName": "Accounting Agent",
"attempt": 1,
"lane": "main",
"outcome": "completed",
"reasonCode": null,
"resultState": "terminal",
"terminal": true,
"startedAt": "2026-11-18T01:30:05.000Z",
"endedAt": "2026-11-18T01:34:40.000Z",
"summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
"errorMessage": null,
"originType": "manual",
"actorLabel": null,
"gateDecision": null,
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"fixTarget": null,
"platformFailure": null,
"rerunOf": null
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId, placement_id, step_id, or run_id is not a UUID, a snake_case name and its earlier name have different values, from or to is not an ISO 8601 time, outcome or fix_target is not one of the values above, reason_code is not in the form of a reason or was specified more than once, q exceeds 200 characters, or limit or cursor is invalid
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

GET/v1/projects/{projectId}/executions/{executionId}

Gets the result of an execution (the run record). An execution of a workflow step can be read with rs:<number> from the execution history, and also with steps[].executionId (a UUID) of the workflow run. executionId in the response is rs:<number>.

Called with a system integration token, it returns only the status fields (executionId, kind, runId, stepId, placementId, attempt, outcome, reasonCode, resultState, terminal, startedAt, and endedAt) (System Integration API Reference).

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
executionIdstring必須Execution ID (rs:<number> or a UUID)

Request Example​

Get execution
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842 \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

In addition to the fields of an item in the execution history, the following fields are returned. summary is up to 2000 characters for a workflow, and for a cycle it is the last message of the conversation as is. For a person with the organization operations role who does not take part in the project, summary, edited, and envelope.completionReport.comment are null, and artifacts, files, inputs, and inputs and writes of library are empty arrays.

FieldTypeDescription
connectionConfirmOfstring | nullAlways null
editedobject | nullAlways null
envelopeobject | nullSummary of the execution
envelope.countsobjectNumbers of tool calls (toolCalls, readCalls, mutatingSuccess, mutatingFailed, unknownCalls, opaqueCalls, workspaceWrites, mcpCalls, and mcpFailed)
envelope.completionReportobject | nullCompletion report of the Agent (completed, reasonCode, fixTarget, comment, and truncated)
envelope.completionReport.fixTargetstring | nullWhat to fix: "goal", "skill", "handoff", "not_assigned", "connection", "rule", "guardrail", "external", or "unknown". null when there is none
envelope.completionReport.commentstring | nullComment of the Agent (up to 2 KB; truncated is true when cut)
envelope.platformFailurestring | nullKind of platform failure (when the outcome is failed or timeout): "cancelled", "signal_cancelled", "kill_timeout", "exception", "invalid_output", "model_refusal", "content_filter", "max_turns", or "loop_limit". null when there is none
envelope.toolsarrayNames of the tools called
usedSettingsobjectSettings used
usedSettings.manifestobject | nullDistributed skills (skill IDs and version IDs), the playbook, guardrails, and so on. Same as the meta of context.manifest in the execution timeline, with field names as recorded
usedSettings.mcpobject | nullMCP connections (numbers and names of configured, connected, and failed servers, and so on). Same as the meta of runtime.mcp.connected in the execution timeline. null for an execution that does not use MCP
questionsarrayQuestions from the Agent (eventId, at, kind, optionsCount, optionsTruncated, and answer)
questions[].answerobject | nullAnswer (at, eventType, actorKind, actorRef, digest, answerKind, and optionIndex). null when there is no record of an answer
gatesarrayReview requests (workItemId, title, status, gateDecision, decidedAt, gateMode, decidedByKind, decidedByRef, waitSource, decisionReason, and destinationLabel)
artifactsarrayArtifacts (artifactId, name, path, format, sha256, and size; the content is not included)
filesarrayFiles (filename, filepath, source, isPrimary, createdAt, and mimeType (application/octet-stream when unknown); size when known). Same form as deliverables in the conversation API. Get the content by passing filepath as path to Get the content of a file (GET /v1/projects/{projectId}/files/content)
configurationobjectExecution settings (policyVersion, policyDigest, policyProfile, model, and mcpConfigVersion)
requestobjectRequest. For a workflow, originType, originRef, triggerId, scheduledAt, runStartedAt, and reworkReason; for a cycle, cron, timezone, jobName, and originKind
jobIdstring | nullJob ID. Can be compared with the jobId in the response of a trigger fire
gateForstring | nullWhich failed step execution this review was created for (rs:<number>)
routedFromstring | nullThe step execution that decided the destination (rs:<number>)
latestring | nullWhy a result that arrived late was not used for progress
inputsarrayInput files (input files registered to the agent and files received from the previous step). filename and handoff (true if received from the previous step)
libraryobjectProject library records. inputs and writes are always empty arrays
  • When …Kind in questions and gates is "human", …Ref is a user ID. Otherwise, …Ref is null.
  • questions includes only the questions within the newest 200 rows of the records of the execution. Read older questions in the execution timeline (rows whose section is "confirmation").
  • files includes up to 20 files.
  • The inputs and writes of library are always empty arrays.
  • Read each tool call in the list of tool calls.

Response Example​

JSON
{
"executionId": "rs:1842",
"kind": "run_step",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"stepName": "Amount check",
"stepPosition": 2,
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"agentName": "Accounting Agent",
"attempt": 1,
"lane": "main",
"outcome": "completed",
"reasonCode": null,
"resultState": "terminal",
"terminal": true,
"startedAt": "2026-11-18T01:30:05.000Z",
"endedAt": "2026-11-18T01:34:40.000Z",
"summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
"errorMessage": null,
"originType": "manual",
"actorLabel": null,
"gateDecision": null,
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"fixTarget": null,
"platformFailure": null,
"rerunOf": null,
"connectionConfirmOf": null,
"edited": null,
"envelope": {
"counts": {
"toolCalls": 14,
"readCalls": 9,
"mutatingSuccess": 3,
"mutatingFailed": 0,
"unknownCalls": 0,
"opaqueCalls": 0,
"workspaceWrites": 3,
"mcpCalls": 0,
"mcpFailed": 0
},
"completionReport": {
"completed": true,
"reasonCode": null,
"fixTarget": null,
"comment": "11 of 12 matched. 1 was turned into a work item because of an amount difference.",
"truncated": false
},
"platformFailure": null,
"tools": [
"read_file",
"write_file"
]
},
"usedSettings": {
"manifest": null,
"mcp": null
},
"questions": [],
"gates": [],
"artifacts": [],
"files": [],
"configuration": {
"policyVersion": null,
"policyDigest": null,
"policyProfile": null,
"model": null,
"mcpConfigVersion": null
},
"request": {
"originType": "manual",
"originRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"triggerId": null,
"scheduledAt": null,
"runStartedAt": "2026-11-18T01:30:00.000Z",
"reworkReason": null
},
"jobId": null,
"gateFor": null,
"routedFrom": null,
"late": null,
"inputs": [
{
"filename": "invoice.json",
"handoff": false
}
],
"library": {
"inputs": [],
"writes": []
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or executionId is neither rs:<number> nor a UUID
403sso_requiredThe user record is not linked to an account of the authorization server
404execution_not_foundThe execution does not exist, belongs to another project, is a sweep execution that has not started yet (also with a system integration), or you are not a member of the project

GET/v1/projects/{projectId}/executions/{executionId}/operations

Gets the list of tool calls in an execution, page by page from the newest records to older ones. Within a page, operations are in oldest-first order. Reading to the end gives all the calls of the execution. Arguments and responses are not included.

Query Parameters​

ParameterTypeDefaultDescription
cursorstring—Cursor for the next page (the cursor value from the previous response)

The number of items per page is not fixed, so there is no limit.

Request Example​

List execution operations
1curl https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/operations \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
operationsarrayArray of calls
operations[].operationIdstring | nullCall ID
operations[].kindstring | nullKind of the row. "tool" (a tool call) / "a2a" (a call to an A2A agent) / "access" (the check before reading a file)
operations[].resourcestring | nullTool (mcp:<server name>:<tool name> for MCP)
operations[].actionstring | nullOperation
operations[].pathstring | nullPath of the file read
operations[].mcpServerstring | nullName of the MCP server
operations[].connectionIdstring | nullConnector ID (connectionId of the connector API)
operations[].connectionKindstring | nullKind of connector ("mcp" or "a2a")
operations[].attemptedbooleanWhether the call was made
operations[].effectstring | nullResult of the call. "ok" (succeeded) / "error" (a tool error) / "failed" (failed). null while the result has not been recorded yet
operations[].deniedstring | nullReason when it was stopped
operations[].durationMsnumber | nullTime taken (milliseconds)
operations[].reasonstring | nullReason of the check (only rows whose kind is "access"; for example, "granted" or "path_not_found"). null for other rows
hasMorebooleanWhether there are more
cursorstringCursor for the next page. Included only when hasMore is true

When the records of one call are split across a page boundary, rows with the same operationId appear on both pages. Treat rows with the same operationId as one call.

Response Example​

JSON
{
"operations": [
{
"operationId": "call:toolu_01ABC",
"kind": "access",
"resource": "read_file",
"action": "read",
"path": "/workspace/invoice.json",
"mcpServer": null,
"connectionId": null,
"connectionKind": null,
"attempted": true,
"effect": null,
"denied": null,
"durationMs": 12,
"reason": "granted"
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or executionId has the wrong form, or cursor is invalid
400invalid_cursorcursor cannot be read
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404execution_not_foundThe execution does not exist, belongs to another project, or you are not a member of the project

GET/v1/projects/{projectId}/executions/{executionId}/timeline

Gets the timeline of an execution (the records of the execution). The records of the request, evidence, actions, confirmations, and result are listed from oldest.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger50Number of rows per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Request Example​

Get execution timeline
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/rs:1842/timeline?limit=50" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
rootExecutionIdstringExecution ID
originstring | nullHow the execution started. "job" (job) / "chat" (chat)
ownerobjectThe owner of the execution
owner.userIdstring | nullUser ID of the owner. null when unknown
executionsobjectSummaries of the execution (items): result, settings, numbers of tool calls, and so on
timelineobjectRecord rows (items)
timeline.items[].atstringTime of the record
timeline.items[].keynumberID of the record. A "tool.access" row corresponds to the operationId of the tool-call list (call:<call ID> for rows with a call ID, row:<key> for rows without)
timeline.items[].sectionstring"request", "evidence", "action", "confirmation", "result", or "other"
timeline.items[].eventTypestringKind of record (for example, "context.manifest", "runtime.mcp.connected", "tool.invoked", or "guardrail.blocked")
timeline.items[].metaobjectContents of each record. Field names are returned as recorded
deletedobjectDeleted conversations and resources
deleted.conversationsstring[]IDs of deleted conversations
deleted.resourcesstring[]Deleted resources (such as files). Only those that appear in timeline.items[].resource on this page
hasMorebooleanWhether there are more
cursorstringCursor for the next page. Included only when hasMore is true
snapshotAtstring | nullWhen the records were read

timeline.items[] also has writer, actor, resource, action, decision, reason, policyVersion, ref, and available. The contents of meta differ by record type, and field names are returned as recorded (snake_case). One page is up to 64 KiB.

Response Example​

JSON
{
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"origin": "job",
"owner": {
"userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"executions": {
"items": [
{
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"origin": "job",
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"job": {
"id": "e3a5c7d9-1b2f-4c6e-8a0b-3d5f7a9c1e2b",
"mode": "once",
"scheduleType": "once",
"deletedAt": null,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"projectAgentId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"projectRunId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13"
},
"ownerUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"messageId": "b2c4d6e8-0a1b-4c3d-9e5f-7a9b1c3d5e7f",
"stepIndex": 0,
"status": "completed",
"startedAt": "2026-11-18T01:30:05.000Z",
"completedAt": "2026-11-18T01:34:40.000Z",
"terminal": {
"state": "terminal",
"outcome": "completed",
"outcomeReasonCode": null,
"hadMutatingSuccess": true,
"terminalAt": "2026-11-18T01:34:40.000Z",
"degradedFrom": null,
"envelopeVersion": 1,
"envelopeAppliedAt": "2026-11-18T01:34:41.000Z"
},
"logical": {
"outcome": "completed",
"hadMutatingSuccess": true,
"terminalAt": "2026-11-18T01:34:40.000Z"
},
"configuration": {
"policyVersion": null,
"policyDigest": null,
"policyProfile": null,
"model": null,
"mcpConfigVersion": null
},
"runtime": {
"podAdoptedAt": null,
"suspendedAt": null,
"interruptedReason": null
},
"alertDelivery": {
"status": null,
"errorPresent": false,
"at": null
},
"envelope": {
"envelopeVersion": 1,
"outcome": "completed",
"hadMutatingSuccess": true,
"counts": {
"toolCalls": 14,
"mutatingSuccess": 3
},
"completionReport": {
"completed": true,
"reasonCode": null,
"fixTarget": null,
"hasComment": true,
"truncated": false
}
},
"occurrence": null,
"projectRun": {
"id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"originType": "manual",
"status": "running",
"currentStepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"snapshotSchemaVersion": 3
},
"runStep": {
"id": "1842",
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"attempt": 1,
"status": "done",
"laneId": null,
"resumeCommandId": null,
"supersededBy": null
},
"startActor": {
"kind": "person",
"ref": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"missing": []
}
]
},
"timeline": {
"items": [
{
"at": "2026-11-18T01:30:06.000Z",
"key": 1201,
"section": "evidence",
"eventType": "context.manifest",
"writer": "worker",
"actor": {
"kind": "agent",
"ref": null,
"onBehalfOf": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"resource": null,
"action": null,
"decision": null,
"reason": null,
"policyVersion": null,
"ref": {
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"messageId": null,
"requestId": null,
"sourceEventId": null,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"rootExecutionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"payloadDigest": null
},
"meta": {},
"available": true
}
]
},
"deleted": {
"conversations": [],
"resources": []
},
"hasMore": false,
"snapshotAt": "2026-11-18T05:40:00.000Z"
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or executionId has the wrong form, limit is not an integer between 1 and 100, or cursor is invalid
400invalid_cursorcursor cannot be read
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404execution_not_foundThe execution does not exist, belongs to another project, or you are not a member of the project
413trace_too_largeThe records are too large to read
502trace_unreachableThe records could not be read (try again later)
503trace_unavailableReading the records is not available

POST/v1/projects/{projectId}/executions/{executionId}/cancel

For a cycle project, stops a sweep execution. This is the same as Stop on the screen. Owners and operators (including people with the organization operations role) can call this API. It can also be called with a system integration token. No body is needed (a body is not used even if sent).

  • Only sweep executions of cycle projects can be stopped. Specifying an execution of a workflow step (rs:<number>) returns 400 Bad Request (invalid_parameter). To stop a workflow run, use Cancel a Workflow Run.
  • After it is accepted, it can take about a minute for the execution to stop. Check whether it stopped with Get the Result of an Execution (GET /v1/projects/{projectId}/executions/{executionId}). It can also be called with a system integration (service account) token (it returns only the status fields). An execution that had not started yet when the stop request was accepted stays 404 Not Found (execution_not_found) in Get the Result of an Execution.
  • For an execution whose stop was already requested, or that had already ended, nothing changes: 200 OK is returned with existing set to true.

Path Parameters​

パラメータ型必須説明
projectIdstring必須Project ID (UUID)
executionIdstring必須ID of the sweep execution (UUID)

Request Example​

Cancel execution
1curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/executions/a1b2c3d4-e5f6-4789-8abc-def012345678/cancel \
2-H "Authorization: Bearer <access_token>"

Response Fields (202 Accepted / 200 OK)​

202 Accepted when a new stop request was accepted, and 200 OK otherwise.

FieldTypeDescription
executionIdstringID of the execution
statestringThe state when the request was accepted. It does not indicate whether the execution actually stopped (see the first bullet of this section for how to check). Example values: "dispatched" (the stop request was passed to the running execution), "cancelled" (an execution that had not started yet was cancelled), "terminal" (the execution had already finished). Other state values of the execution or the dispatch at the time of acceptance may also be returned as they are. Do not fix a list of values and rely on it
existingbooleantrue when a stop had already been requested or the execution had already ended (always false with 202 Accepted)

Response Example​

JSON
{
"executionId": "a1b2c3d4-e5f6-4789-8abc-def012345678",
"state": "dispatched",
"existing": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, executionId is neither rs:<number> nor a UUID, or executionId is an execution of a workflow step
400invalid_bodyThe body is malformed JSON or not a JSON object
403operator_onlyA member who is neither an owner nor an operator and does not have the organization operations role
403sso_requiredThe user record is not linked to an account of the authorization server
404execution_not_foundThe execution does not exist, belongs to another project, the project is not a cycle, or you are not a member of the project
413body_too_largeThe body exceeds 16 KiB
415unsupported_media_typeA request body is sent with a Content-Type other than application/json

Files​

Gets the content of files found in a project (files[] in execution results, evidence.files[] in review request evidence). In each case, pass the filepath from the response to path as is.

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/files/contentGet the content of a file

GET/v1/projects/{projectId}/files/content

Gets the content of a file. Only project members can read it (even for a shared project, a non-member gets 404; a person with the organization operations role who does not take part in the project gets 400 Bad Request (file_not_found)). It can also be called with HEAD. The same headers are returned without the body, so you can check the size first. It can also be called with the token used for MCP, so a file URL returned by an MCP tool can be fetched with the same token.

Path Parameters​

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

Query Parameters​

ParameterTypeDefaultDescription
pathstring—Required. The file path (files[].filepath in an execution result, or evidence.files[].filepath in a review request)
version_idstring—ID of a version. The current version if omitted

For files in execution results, the readable versions are the current version and the versions written after the execution in which the project first recorded the file started.

Request Example​

Get project file content
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/files/content?path=/users/f47ac10b-58cc-4372-a567-0e02b2c3d479/plans/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/deliverables/report.pdf" \
2-H "Authorization: Bearer <access_token>"

Response (200 OK)​

The content of the file is returned as is.

Response HeaderDescription
Content-TypeMIME type of the file
Content-LengthFile size in bytes. Present only when the size is known
Accept-Ranges"bytes" (present only when the size is known)
X-Content-Type-Options"nosniff"
Content-Disposition"attachment" for HTML, SVG, and XML files (returned as a download)
Content-Security-PolicyFor HTML, SVG, and XML files, a policy that blocks script execution and external loading (sandbox and others) is set

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or path is missing
400file_not_foundThe file specified by path cannot be read
400version_not_foundThe version specified by version_id does not exist (the file can be read)
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

Storage failures (500, 502, and 503) are the same as Artifact Retrieval (GET /v1/files/proxy).

Records (Audit Trail)​

A list of certain operations and events in a project (review decisions, changes to execution rules and members, tool records in executions, and so on). The setting changes that are kept are changes to execution rules, reviewers, the review method, members, and project webhooks (including changes made on the screen). Changes to the project definition (basic information, execution rules, steps, placements, triggers, app and email notifications, and connectors) are kept field by field as project.definition_changed when a definition version is recorded, as the difference from the previous version (long fields such as the description and goal are kept as their length only). Changes to sweeps and to outgoing webhook notifications are not kept.

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/auditGet the records (audit trail)

GET/v1/projects/{projectId}/audit

Gets the records (audit trail), newest first. Cursor-based pagination is supported.

Query Parameters​

ParameterTypeDefaultDescription
kindstring—Filter by kind of record (for example, "policy.changed", "improvement.applied", or "tool.invoked")
run_idstring—Filter to the records of this workflow run (UUID)
qstring—Filter by text (up to 100 characters)
limitinteger50Number of items per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Request Example​

List audit events
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/audit?kind=policy.changed&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
eventsarrayArray of records
events[].eventIdnumberRecord ID
events[].occurredAtstring | nullTime (ISO 8601)
events[].eventTypestring | nullKind of record
events[].actorKindstring | nullKind of recorder: "agent", "human", "system", "human_external", "mail_external", or "unknown"
events[].actorRefstring | nullRecorder. A user ID when actorKind is "human"; otherwise a reference (client:<client ID> for a system integration, and so on)
events[].decisionstring | nullDecision or result
events[].reasonstring | nullReason
events[].executionIdstring | nullExecution ID
events[].runIdstring | nullID of the workflow run
events[].stepNamestring | nullStep name
events[].metadataobjectContents of each record. Field names are returned as recorded. {} for a record without contents
hasMorebooleanWhether there is a next page
cursorstringCursor for the next page. Included only when hasMore is true
  • Identify rows of system integrations by client:<integration ID> in actorRef. Read the display name of an integration from actorLabel in the execution history or the execution result.
  • Some records during an execution (context.manifest, runtime.*, and so on) are not included. Read them in the execution timeline.

Response Example​

JSON
{
"events": [
{
"eventId": 1042,
"occurredAt": "2026-11-18T04:20:11.000Z",
"eventType": "policy.changed",
"actorKind": "human",
"actorRef": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"decision": null,
"reason": null,
"executionId": null,
"runId": null,
"stepName": null,
"metadata": {}
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId or run_id is not a UUID, run_id and runId have different values, kind is not in the form of a kind of record, q exceeds 100 characters, or limit or cursor is invalid
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

KPI​

Gets the same values as "Results of this work" in the overview on the screen (the per-step steps are the values shown under "Metrics" in "Workflow shape"; the values of the review steps alone are also in gates). For how they are counted, see the Results Reference (for the per-step values, Figures by step).

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/kpiGet the KPIs

GET/v1/projects/{projectId}/kpi

Gets the KPIs of a project. Project members and people with the organization operations role can read them (even for a shared project, anyone else gets 404).

Query Parameters​

ParameterTypeDefaultDescription
daysinteger30Period (the most recent days). One of 7, 30, or 90

Request Example​

Get project KPI
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/kpi?days=30" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
daysnumberPeriod (days)
successRatenumber | nullAgent completion rate (0 to 1; completed ÷ finished). null when finished is 0
successRateStatusstring"ok" (final), "incomplete" (provisional because a record is insufficient), or "none" (no record is insufficient and finished is 0)
succeedednumberNumber of completed executions
denominatornumberNumber of finished executions (Completed plus "Failed / needs action"; executions that finished with no change are not counted)
executionsnumberNumber of finished executions (the sum of denominator and noChange)
noChangenumberNumber of executions that finished with no change (the result is completed and the reason is "no_change"). Not counted in finished or successful completions
outcomesobjectNumbers per outcome (completed, incomplete, failed, timeout, stopped, denied, and skipped). completed includes executions that finished with no change
excludedobjectNumbers not counted (skipped, running, missing, unmeasured, and connectionConfirm). connectionConfirm is always 0
durationP95Minutesnumber | nullProcessing time guide (p95, minutes)
runsobjectNumbers of workflow runs (total, closedDone, closedFailed, closedRejected, and cancelled) and p95Minutes
gatesarrayResults per review step (stepId, position, name, mode, total, approvalRate, and sendBackRate). When steps is an array and the gate of a review step's row is not null, total, approvalRate, and sendBackRate are the same as in that gate
stepsarray | nullResults per step. Lists the enabled steps in position order (stepId, position, name, defaultZone, agent, gate, and automation). Only the one of agent, gate, and automation that matches the type of the step is set, and the others are null. For a branch step, all of them are null. null when it cannot be obtained
steps[].namestringStep name (for a step without a name, a name made in the project's language, or in the service's default language if the project has none)
steps[].defaultZonestring | nullStep type. One of "ai" (run by an Agent), "gate" (review step) and "branch" (branch)
steps[].agentobject | nullResults of an Agent step: the same items as the Agent completion rate above (executions, succeeded, denominator, noChange, successRate, successRateStatus, outcomes, excluded, and durationP95Minutes), counted from the executions of that step only
steps[].gateobject | nullResults of a review step (mode, total, approvalRate, sendBackRate, waitMedianMinutes, and deadlineDecisions). deadlineDecisions is counted in the same way as human.deadlineDecisions, from the review requests of that step only; as with human.deadlineDecisions, rate is null when total is 0
steps[].automationobject | nullAlways null (there are no external automation steps)
humanobjectReview handling (reviewsPerRun, gateWaitMedianMinutes, interventions, and deadlineDecisions)
human.deadlineDecisionsobject | nullOf the reviews with a deadline, how many a person decided in time (total: decided or past the deadline; onTime: decided by a person by the deadline; rate: onTime / total, null when total is 0). Automatic decisions at the deadline are not counted as on time

The Agent completion rate, runs, gates, steps, and human count executions, workflow runs, and review requests that started in the period.

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, or days is not 7, 30, or 90
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

Response Example​

JSON
{
"days": 30,
"successRate": 0.9318,
"successRateStatus": "ok",
"succeeded": 41,
"denominator": 44,
"executions": 46,
"noChange": 2,
"outcomes": {
"completed": 43,
"incomplete": 2,
"failed": 1,
"timeout": 0,
"stopped": 0,
"denied": 0,
"skipped": 1
},
"excluded": {
"skipped": 1,
"running": 1,
"missing": 2,
"unmeasured": 0,
"connectionConfirm": 0
},
"durationP95Minutes": 14,
"runs": {
"total": 24,
"closedDone": 20,
"closedFailed": 2,
"closedRejected": 1,
"cancelled": 1,
"p95Minutes": 22
},
"gates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "Amount check",
"mode": "blocking",
"total": 17,
"approvalRate": 0.88,
"sendBackRate": 0.12
}
],
"steps": [
{
"stepId": "2b3c4d5e-6f70-4819-a2b3-c4d5e6f70812",
"position": 1,
"name": "Read invoices",
"defaultZone": "ai",
"agent": {
"executions": 46,
"succeeded": 41,
"denominator": 44,
"noChange": 2,
"successRate": 0.9318,
"successRateStatus": "ok",
"durationP95Minutes": 14,
"outcomes": {
"completed": 43,
"incomplete": 2,
"failed": 1,
"timeout": 0,
"stopped": 0,
"denied": 0,
"skipped": 1
},
"excluded": {
"skipped": 1,
"running": 1,
"missing": 2,
"unmeasured": 0,
"connectionConfirm": 0
}
},
"gate": null,
"automation": null
},
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"position": 2,
"name": "Amount check",
"defaultZone": "gate",
"agent": null,
"gate": {
"mode": "blocking",
"total": 17,
"approvalRate": 0.88,
"sendBackRate": 0.12,
"waitMedianMinutes": 35,
"deadlineDecisions": {
"total": 15,
"onTime": 14,
"rate": 0.9333
}
},
"automation": null
}
],
"human": {
"reviewsPerRun": 0.7,
"gateWaitMedianMinutes": 35,
"interventions": 17,
"deadlineDecisions": {
"total": 15,
"onTime": 14,
"rate": 0.9333
}
}
}

Review Requests​

A review request is created when a workflow reaches a review step, or when an Agent step returns "Not allowed by rules" or "Failed (reported by agent)" and that step is set to ask for review. The reviewers decide whether to proceed, send it back, or reject it. It is the same as a review request on the screen.

  • Reviewers (the reviewers when the review request was created who are still members of the project), their delegates during the delegation period, and the owners of the project can read it. Other users get 404 Not Found (workitem_not_found).
  • Only reviewers and their delegates during the delegation period can decide. An owner who is neither cannot (403 Forbidden, not_gate_owner). The due date can also be extended by owners, operators, and people with the organization operations role. A reviewer sets a delegate in the settings screen (Out of office): one user in the same organization, for a set period. The delegate does not have to be a member of the project.

Endpoint List​

メソッドエンドポイント説明
GET/v1/workitemsGet the list of review requests
GET/v1/workitems/{workItemId}Get a review request
POST/v1/workitems/{workItemId}/decisionDecide a review request
PATCH/v1/workitems/{workItemId}Extend the due date of a review request

GET/v1/workitems

Gets the review requests you can read, most recently updated first, across projects. Cursor-based pagination is supported.

Query Parameters​

ParameterTypeDefaultDescription
statusstring—Filter by state: "assigned" (waiting for review), "done" (proceeded or sent back), or "cancelled" (rejected, or cancelled because the workflow run stopped)
statestring—Filter by "open" (assigned and not yet decided) or "closed" (anything else)
project_idstring—Filter to the review requests of this project (UUID)
limitinteger50Number of items per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Request Example​

List work items
1curl "https://<your-domain>/api/v1/workitems?state=open&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
workitemsarrayArray of review requests
workitems[].workItemIdstringReview request ID (UUID)
workitems[].titlestring | nullTitle
workitems[].statusstring | null"assigned", "done", or "cancelled"
workitems[].projectIdstring | nullProject ID
workitems[].projectNamestring | nullProject name
workitems[].decisionstring | nullDecision: "proceed", "send_back", or "reject". null before a decision
workitems[].requesterUserIdstring | nullUser ID of the requester
workitems[].expiresAtstring | nullReview deadline (ISO 8601)
workitems[].gateModestring | nullAlways "blocking" (wait for the reviewer's decision)
workitems[].overdueboolean | nullWhether the deadline has passed
workitems[].decidedAtstring | nullWhen it was decided (ISO 8601)
workitems[].createdAtstring | nullCreation time (ISO 8601)
workitems[].updatedAtstring | nullUpdate time (ISO 8601)
workitems[].canDecidebooleanWhether you can decide (true for a reviewer, or for their delegate during the delegation period)
hasMorebooleanWhether there is a next page
cursorstringCursor for the next page. Included only when hasMore is true

Response Example​

JSON
{
"workitems": [
{
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "Check invoices with differences",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "Invoice reconciliation",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-20T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterstatus or state is not one of the values above, project_id is not a UUID, project_id and projectId have different values, or limit or cursor is invalid
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server

GET/v1/workitems/{workItemId}

Gets a review request, with the material for the review, its history, and the destinations you can choose.

Path Parameters​

パラメータ型必須説明
workItemIdstring必須Review request ID (UUID)

Request Example​

Get work item
1curl https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
workitemobjectThe review request: the fields of an item in the list (workItemId, title, status, projectId, decision, requesterUserId, expiresAt, gateMode, overdue, decidedAt, createdAt, updatedAt, and canDecide) and the following fields
workitem.descriptionstring | nullDescription
workitem.runIdstring | nullID of the workflow run
workitem.runStepIdstring | nullExecution ID of the step that asked for the review (rs:<number>; the same form as executionId in the execution history)
workitem.stepIdstring | nullID of the step that asked for the review (a review step, or an Agent step that asked for a review because of its outcome)
workitem.approverUserIdsarrayArray of user IDs of the reviewers (the reviewers when the review request was created)
workitem.overdueActionstring | nullAlways "none" (nothing is decided automatically after the deadline; the reviewers are notified and it keeps waiting)
workitem.evidenceobject | nullMaterial for the review (see the table below)
workitem.decidedByKindstring | nullKind of what decided (for example, "human"). null before a decision
workitem.decidedByRefstring | nullWhat decided. A user ID when decidedByKind is "human". An automatic decision after the deadline and the like is a system:… reference. null before a decision
workitem.decisionReasonstring | nullReason for the decision
workitem.sendBackToStepIdstring | nullID of the step sent back to
workitem.decisionResultobject | nullResult of the decision (decision, at, completesRun, sendBackToStepId, destinationId, and destinationStepId). completesRun is whether proceeding finished the workflow run
activitiesarrayHistory (newest first, up to 100 items)
activities[].activityIdnumber | nullHistory ID
activities[].eventTypestring | nullKind of record
activities[].decisionstring | nullDecision
activities[].actorKindstring | nullKind of recorder
activities[].actorRefstring | nullRecorder. A user ID when actorKind is "human"; otherwise a reference such as system:…
activities[].onBehalfOfRefstring | nullWhen a delegate decided, the user ID of the reviewer they acted for. null when, for example, the reviewer decided themselves
activities[].reasonCodestring | nullReason ("branch_undecided" when a branch could not decide and a person is asked to choose)
activities[].conversationIdstring | nullConversation ID
activities[].metadataobjectContents of each record. Field names are returned as recorded (they may contain user IDs)
activities[].occurredAtstring | nullTime (ISO 8601)
gateobject | nullInformation for the decision (see the table below)

Material for the review (workitem.evidence):

FieldTypeDescription
summarystring | nullText for the review. Usually the output of the Agents of the reviewed step; when an Agent step asked for a review because of its outcome, a summary of the outcome and its reason
conversationIdstring | nullID of the execution conversation of the reviewed step
filesarrayFiles of the reviewed step (same form as deliverables in the conversation API. Get the content by passing filepath as path to Get the content of a file (GET /v1/projects/{projectId}/files/content))
gateKindstring | nullKind of review: "review" (review) or "manual" (manual work)
stepNamestring | nullName of the step that asked for the review
outcomestring | nullOutcome of the execution of the reviewed step (see "Outcome Values" of executions)
executionIdstring | nullExecution ID of the reviewed step (can be read with Get the result of an execution)
reasonCodestring | nullReason for the outcome (when an Agent step asked for a review because of its outcome; "branch_undecided" for a review where a branch could not decide and a person chooses)
escalateToUserIdstring | nullUser ID of the contact after the deadline (a person who was a member when the review request was created)
destinationsarrayOnly for a review raised by a branch step: the choices of where to go (destinationId, label, stepId, and branchRoute: {"kind": "lane", "laneId"} or {"kind": "merge"}). Always an empty array for other review requests (destinations cannot be set on review steps in the Marketplace edition)
connectorobject | nullAlways null
servicestring | nullAlways null
modestring | nullAlways null
toolstring | nullAlways null
waitMinutesnumber | nullAlways null

Information for the decision (gate):

FieldTypeDescription
contextVersionnumberVersion of the review request (1 or more). Included only for a versioned review (a workflow review). Send it as is in contextVersion of the decision
basisDigeststring | nullDigest of the review material (64 hexadecimal characters). Included only when contextVersion is. Send it as is in basisDigest of the decision
projectNamestring | nullProject name
projectTypestring | nullProject type
stepIdstring | nullID of the step that asked for the review
stepNamestring | nullName of the step that asked for the review
stepPositionnumber | nullPosition of the step that asked for the review
nextStepobject | nullThe next step when proceeding (stepId, name, and position). null when there is no next step
sendBackDefaultStepIdstring | nullID of the step sent back to when no send-back step is specified
sendBackCandidatesarraySteps you can specify as the send-back step (stepId, name, position, and sendBacks). sendBacks is the number of times sent back to that step
sendBackLimitnumber | nullMaximum number of send-backs to one step
destinationsarrayOnly for a review raised by a branch step: the choices of where to go (destinationId, label, stepId, stepName, stepPosition, and branchRoute: {"kind": "lane", "laneId"} or {"kind": "merge"}). Always an empty array for other review requests (destinations cannot be set on review steps in the Marketplace edition)
laneobject | nullLane of the step that asked for the review (laneId, name, and position). null when there are no lanes

Response Example​

JSON
{
"workitem": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "Check invoices with differences",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-20T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true,
"description": "1 of the 12 invoices has an amount difference.",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"runStepId": "rs:1843",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"overdueAction": "none",
"evidence": {
"summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"files": [],
"gateKind": "review",
"stepName": "Amount check",
"outcome": "completed",
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"reasonCode": null,
"escalateToUserId": null,
"destinations": [],
"connector": null,
"service": null,
"mode": null,
"tool": null,
"waitMinutes": null
},
"decidedByKind": null,
"decidedByRef": null,
"decisionReason": null,
"sendBackToStepId": null,
"decisionResult": null
},
"activities": [
{
"activityId": 5301,
"eventType": "gate.requested",
"decision": "requested",
"actorKind": "system",
"actorRef": "system:completion-apply",
"onBehalfOfRef": null,
"reasonCode": "review",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"metadata": {
"workitem_id": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"run_id": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"step_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"gate_mode": "blocking",
"gate_kind": "review"
},
"occurredAt": "2026-11-18T01:34:40.000Z"
}
],
"gate": {
"contextVersion": 1,
"basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
"projectName": "Invoice reconciliation",
"projectType": "workflow",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"stepName": "Difference check",
"stepPosition": 2,
"nextStep": {
"stepId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"name": "Difference report",
"position": 3
},
"sendBackDefaultStepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"sendBackCandidates": [
{
"stepId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
"name": "Amount check",
"position": 1,
"sendBacks": 0
}
],
"sendBackLimit": 3,
"destinations": [],
"lane": null
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterworkItemId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404workitem_not_foundThe review request does not exist, or you cannot read it

POST/v1/workitems/{workItemId}/decision

Decides a review request. Only reviewers and their delegates during the delegation period can call it.

Request Body​

FieldTypeRequiredDescription
decisionstringYes"proceed", "send_back", or "reject"
reasonstring—Reason (up to 10000 characters). Required for "send_back" and "reject"
sendBackToStepIdstring—ID of the step to send back to (for "send_back"; a step in sendBackCandidates of gate). If omitted, it is sent back to the step in sendBackDefaultStepId
destinationIdstring—Destination (for "proceed"; destinationId in destinations of gate; up to 64 characters). Required to proceed a review request that has destinations
commandIdstring—A value to identify resends (up to 128 characters)
contextVersioninteger—gate.contextVersion of the review request you read before deciding (an integer of 1 or more). Required when gate includes it
basisDigeststring—gate.basisDigest of the review request you read before deciding (64 lowercase hexadecimal characters). Required when gate includes it
  • If you resend the same content with the same commandId, the result of the first request ({ "decision": …, "alreadyDecided": true }) is returned. Sending different content with the same commandId returns 409 Conflict (command_conflict).
  • Sending to a review request that has already been decided with a different commandId (or without commandId) returns 409 Conflict (already_decided). Get the review request again and read the current decision.
  • Send-backs are allowed up to the maximum number of send-backs to one step (gate.sendBackLimit).

For a versioned review, if the review request changed after you read it, 409 Conflict (stale_context) is returned. Get the review request again, and send the new gate.contextVersion and gate.basisDigest.

Request Example​

Decide work item
1curl -X POST https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432/decision \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "decision": "proceed",
6 "reason": "The difference was between tax-included and tax-excluded amounts",
7 "contextVersion": 1,
8 "basisDigest": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
9 "commandId": "decide-20261118-0001"
10}'

Response Fields (200 OK)​

FieldTypeDescription
decisionstringDecision
channelstring | nullHow it was decided ("api" when decided through the API). Not included in the response to a resend
alreadyDecidedbooleanIncluded as true only when a resend with the same commandId returned the result of the first request

Response Example​

JSON
{
"decision": "proceed",
"channel": "api"
}

Error Responses​

StatuscodeDescription
400invalid_parameterworkItemId or sendBackToStepId is not a UUID, decision is missing or not one of the values above, commandId or destinationId is only whitespace, contextVersion is not an integer of 1 or more, basisDigest is not 64 lowercase hexadecimal characters, or a field has the wrong type or length
400invalid_parametersendBackFiles was sent (this API does not accept it)
400invalid_bodyThe body is malformed JSON or not a JSON object
400reason_requiredreason is missing for "send_back" or "reject"
400invalid_send_back_stepsendBackToStepId is not a step that can be specified as the send-back step
400destination_requiredTried to proceed a review request that has destinations without destinationId
400invalid_destinationdestinationId is not one of the destinations, or destinationId was sent with a decision other than "proceed"
400basis_requiredcontextVersion and basisDigest were not sent for a versioned review
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
403not_gate_ownerA member of the project who is not a reviewer
404workitem_not_foundThe review request does not exist, or you cannot read it
409already_decidedIt has already been decided
409command_conflictDifferent content was sent with the same commandId
409invalid_stateIt is not waiting for review (for example, it was cancelled)
409send_back_limit_exceededThe maximum number of send-backs has been reached
409stale_contextThe review request changed after you read it (the version sent is different from the current version)
413body_too_largeThe body exceeds 3 MiB
415unsupported_media_typeThe Content-Type of the body is not application/json

PATCH/v1/workitems/{workItemId}

Extends the due date (expiresAt) of a review request. Reviewers, their delegates during the delegation period, and owners and operators (including people with the organization operations role) can call this API. Extending it also clears the overdue flag (overdue).

Path Parameters​

パラメータ型必須説明
workItemIdstring必須ID of the review request (UUID)

Request Body​

FieldTypeRequiredDescription
expiresAtstringYesNew due date (an ISO 8601 date-time in the future)

Resending the same value gives the same result.

Request Example​

Extend work item
1curl -X PATCH https://<your-domain>/api/v1/workitems/c9d8e7f6-a5b4-4321-8fed-cba098765432 \
2-H "Authorization: Bearer <access_token>" \
3-H "Content-Type: application/json" \
4-d '{
5 "expiresAt": "2026-11-22T09:00:00.000Z"
6}'

Response Fields (200 OK)​

FieldTypeDescription
workitemobject | nullThe review request after the extension. The fields are the same as workitem in Get a Review Request. null when someone who cannot read the review request (an operator or a person with the organization operations role who is not a reviewer, a delegate, or an owner) extended it
expiresAtstringThe due date after the extension (ISO 8601)
previousExpiresAtstring | nullThe due date before the extension (ISO 8601)

If the due date is extended and reading the review request back then fails for a reason other than not being able to read it (404), 502 Bad Gateway (upstream_connection_error) is returned. The due date may already have been extended, so if you can read the review request, check expiresAt with Get a Review Request before resending.

Response Example​

JSON
{
"workitem": {
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"title": "Check invoices with differences",
"status": "assigned",
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"decision": null,
"requesterUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"expiresAt": "2026-11-22T09:00:00.000Z",
"gateMode": "blocking",
"overdue": false,
"decidedAt": null,
"createdAt": "2026-11-18T01:34:40.000Z",
"updatedAt": "2026-11-18T01:34:40.000Z",
"canDecide": true,
"description": "1 of the 12 invoices has an amount difference.",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"runStepId": "rs:1843",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"approverUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"overdueAction": "none",
"evidence": {
"summary": "Matched 12 invoices and turned the 1 with a difference into a work item.",
"conversationId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"files": [],
"gateKind": "review",
"stepName": "Amount check",
"outcome": "completed",
"executionId": "a4c6e8f0-1b3d-4a5c-9e7f-2d4b6a8c0e1f",
"reasonCode": null,
"escalateToUserId": null,
"destinations": [],
"connector": null,
"service": null,
"mode": null,
"tool": null,
"waitMinutes": null
},
"decidedByKind": null,
"decidedByRef": null,
"decisionReason": null,
"sendBackToStepId": null,
"decisionResult": null
},
"expiresAt": "2026-11-22T09:00:00.000Z",
"previousExpiresAt": "2026-11-20T09:00:00.000Z"
}

Error Responses​

StatuscodeDescription
400invalid_parameterworkItemId is not a UUID, or expiresAt is missing, is not an ISO 8601 date-time, or is not in the future
400invalid_bodyThe body is malformed JSON or not a JSON object
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
403not_gate_ownerA member of the project who is neither a reviewer, a delegate, an owner, nor an operator, and does not have the organization operations role
404workitem_not_foundThe review request does not exist, or you are neither a reviewer, a delegate, a member of the project, nor a person with the organization operations role
409already_decidedIt has already been decided
409invalid_stateIt is not waiting for review (for example, it was cancelled)
413body_too_largeThe body exceeds 3 MiB
415unsupported_media_typeThe Content-Type of the body is not application/json
502upstream_connection_errorThe due date was extended, and reading the review request back failed for a reason other than not being able to read it (404) (if you can read the review request, check with Get a Review Request before resending)

Queue​

The queue lists the things that need a person (overdue review requests, requests waiting for review, failed observations of external waits, workflow runs past their deadline or stalled, failed steps, steps waiting after a send-back, and failed sweeps), one row per item, in order of priority. It is the same as “Action needed” on the screen.

  • The project queue (GET /v1/projects/{projectId}/queue) returns all rows of the project. Members of the project and people with the organization operations role can read it.
  • Your queue (GET /v1/queue) returns the rows you are assigned to, across the projects you take part in. While you are someone's delegate, it also returns that person's review request rows.
  • To act on a row, pass the ID it carries (not the row ID, queueItemId) to the following APIs.
What to doAPIID to use
Proceed, send back, or reject a review requestPOST /v1/workitems/{workItemId}/decisionworkItemId
Extend the due date of a review requestPATCH /v1/workitems/{workItemId}workItemId
Change the deadline of a workflow runPATCH /v1/projects/{projectId}/runs/{runId}runId
Reassign the reviewers of a workflow runPUT /v1/projects/{projectId}/runs/{runId}/approversrunId

Endpoint List​

メソッドエンドポイント説明
GET/v1/projects/{projectId}/queueGet the queue of a project
GET/v1/queueGet the queue of rows you are assigned to

Kinds of Rows​

The values of kind (the kind of row).

ValueShown on the screenWhat it is
gate_overdueOverdueA review request past its due date
run_deadline_overduePast deadline (run)A workflow run past its deadline
external_wait_blockedWaiting on externalA review request whose external wait cannot be observed
gate_pendingAwaiting approvalA review request waiting for review
run_stalledStalledA workflow run that has stopped moving
execution_failedFailedA failed step
send_back_pendingAwaiting reworkA step that was sent back and is waiting
sweep_failedSweep failedA failed sweep

GET/v1/projects/{projectId}/queue

Gets the queue of a project in order of priority. The order is priority, then due date, then the start point of the elapsed time, then the target ID (the part of the row ID after :), and cannot be changed. Supports cursor-based pagination.

Path Parameters​

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

Query Parameters​

ParameterTypeDefaultDescription
kindstring—Filter by kind of row (a value in "Kinds of Rows" above)
limitinteger50Number of items per page (1-100)
cursorstring—Cursor for the next page (the cursor value from the previous response)

Request Example​

List project queue
1curl "https://<your-domain>/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/queue?kind=gate_pending&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
queueItemsarrayArray of queue rows
queueItems[].queueItemIdstringRow ID, in the form <target type>:<target ID>. The target type is one of four: workitem (review request rows: gate_overdue, external_wait_blocked, gate_pending), run_step (failed steps and steps awaiting rework), placement (failed sweeps), and run (workflow runs past their deadline or stalled). It is not the kind of the row (kind): when a review request changes from gate_pending to gate_overdue, the ID stays the same. To tell rows apart, use the returned value as is; do not build or split it. To act on a row, use workItemId, runId or executionId
queueItems[].kindstringKind of row (see "Kinds of Rows" above)
queueItems[].prioritynumber | nullPriority (1 to 4; 1 is the highest)
queueItems[].projectIdstring | nullID of the project
queueItems[].projectNamestring | nullName of the project
queueItems[].workItemIdstring | nullID of the review request. Only for review request rows (gate_overdue, external_wait_blocked, gate_pending); otherwise null. Can be used as is with the review request APIs
queueItems[].runIdstring | nullID of the workflow run. null when absent
queueItems[].stepIdstring | nullID of the step. null when absent
queueItems[].placementIdstring | nullID of the placement. null when absent
queueItems[].executionIdstring | nullID of the execution. Can be used as is to get the execution result. rs:<number> for a failed step (execution_failed), the UUID of the sweep execution for a failed sweep (sweep_failed), and the same value as the review material (evidence.executionId) for review request rows. Otherwise null
queueItems[].stepNamestring | nullName of the step
queueItems[].agentNamestring | nullName of the Agent
queueItems[].titlestring | nullTitle of the review request. Only for review request rows; otherwise null
queueItems[].dueAtstring | nullDue date (ISO 8601): the due date of the review request or the deadline of the workflow run. Otherwise null
queueItems[].elapsedFromstring | nullStart point for counting the elapsed time (ISO 8601). For review request rows, when the review request was created
queueItems[].assigneeUserIdsarrayUser IDs of the assignees: the reviewers for review request rows, and the reviewers of the review that sent it back for rows waiting after a send-back (in both cases, people who are still members). The owners of the project for failed steps, failed sweeps, and workflow runs past their deadline or stalled. For review request rows returned to you as a delegate, these are still the reviewers, not you
queueItems[].escalateToUserIdstring | nullUser ID of the contact when overdue. Only for review request rows; otherwise null
queueItems[].causeobject | nullFor rows that come from a failure, the result (outcome) and reason (reasonCode). Otherwise null
queueItems[].gateKindstring | nullKind of review (same values as gateKind in the review material)
queueItems[].observationErrorCodestring | nullReason the observation of the external wait failed
queueItems[].sendBackLimitReachedboolean | nullWhether the maximum number of send-backs has been reached
hasMorebooleanWhether there is a next page
cursorstringCursor for the next page. Included only when hasMore is true

Response Example​

JSON
{
"queueItems": [
{
"queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
"kind": "gate_pending",
"priority": 3,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "Invoice reconciliation",
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"executionId": null,
"stepName": "Difference check",
"agentName": "Accounting Agent",
"title": "Check invoices with differences",
"dueAt": "2026-11-20T09:00:00.000Z",
"elapsedFrom": "2026-11-18T01:30:00.000Z",
"assigneeUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"escalateToUserId": null,
"cause": null,
"gateKind": "review",
"observationErrorCode": null,
"sendBackLimitReached": false
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterprojectId is not a UUID, kind is not one of the values above, or limit or cursor is invalid
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server
404project_not_foundThe project does not exist, or you are not a member

GET/v1/queue

Gets the rows you are assigned to, across the projects you take part in, and the review requests you can decide as an active delegate, in order of priority. Delegate rows can come from projects you are not a member of; you can read, decide, and extend those review requests with workItemId. The query parameters, response fields, and order are the same as the project queue.

Request Example​

List my queue
1curl "https://<your-domain>/api/v1/queue?kind=gate_pending&limit=20" \
2-H "Authorization: Bearer <access_token>"

Response Example​

JSON
{
"queueItems": [
{
"queueItemId": "workitem:c9d8e7f6-a5b4-4321-8fed-cba098765432",
"kind": "gate_pending",
"priority": 3,
"projectId": "3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31",
"projectName": "Invoice reconciliation",
"workItemId": "c9d8e7f6-a5b4-4321-8fed-cba098765432",
"runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
"stepId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"placementId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"executionId": null,
"stepName": "Difference check",
"agentName": "Accounting Agent",
"title": "Check invoices with differences",
"dueAt": "2026-11-20T09:00:00.000Z",
"elapsedFrom": "2026-11-18T01:30:00.000Z",
"assigneeUserIds": [
"f47ac10b-58cc-4372-a567-0e02b2c3d479"
],
"escalateToUserId": null,
"cause": null,
"gateKind": "review",
"observationErrorCode": null,
"sendBackLimitReached": false
}
],
"hasMore": false
}

Error Responses​

StatuscodeDescription
400invalid_parameterkind is not one of the values above, or limit or cursor is invalid
403forbiddenCalled with a system integration token
403sso_requiredThe user record is not linked to an account of the authorization server

Connectors​

Reads the MCP servers and A2A agents used by project executions. Only the information the other side publishes (tool names and descriptions, and the agent card) is returned. Endpoint URLs and credentials are not returned.

  • You can find the connector ID (connectionId) in connectors[].connectionId of Get Project and in operations[].connectionId of the list of tool calls.
  • Any user of the tenant can read any connector (even without being a member of the project). However, an MCP connector that is limited to certain organizations or job types in the admin console returns 404 Not Found (connector_not_found) to people who cannot use it. With projectId, this is decided by the organization and job type of the project's owner, as on the project's screen (without it, by those of the caller; when the caller is a system administrator, this limit does not apply and the connector can be read through this API). A connector that was disabled or deleted in the admin console also returns 404 Not Found (connector_not_found).
  • Sign-in to a connector is done on the project screen.

Endpoint List​

メソッドエンドポイント説明
GET/v1/connectors/mcp/{connectionId}Get an MCP connector
GET/v1/connectors/a2a/{connectionId}Get an A2A connector

GET/v1/connectors/mcp/{connectionId}

Gets an MCP connector and its list of tools. The list of tools is the one fetched from the MCP server and saved in the admin console.

Path Parameters​

パラメータ型必須説明
connectionIdstring必須Connector ID (a positive integer of up to 16 digits)

Query Parameters​

パラメータ型必須説明
projectIdstring—The ID (UUID) of the project that uses the connector. With it, whether the connector can be used is decided by the organization and job type of the project's owner. Only members of the project and people with the organization operations role can pass it.

Request Example​

Get MCP connector
1curl "https://<your-domain>/api/v1/connectors/mcp/12?projectId=3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31" \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
kindstring"mcp"
connectionIdstringConnector ID
namestring | nullConnector name
requiresLoginbooleanWhether you must sign in on the project screen before using the connector
toolsarrayArray of tools
tools[].namestring | nullTool name
tools[].displayNamestring | nullDisplay name
tools[].descriptionstring | nullDescription
tools[].inputSchemaobject | nullInput schema of the tool (as declared by the MCP server). null until the list of tools is fetched again in the admin console
tools[].outputSchemaobject | nullOutput schema of the tool (as declared by the MCP server). null if not declared
tools[].declaredAnnotationsobject | nullTool annotations (such as readOnlyHint, as self-declared by the MCP server). This product does not verify them and does not use them to control execution
tools[].presentInLastFetchboolean | nullWhether it was also there the last time the list was fetched (false means the tool is gone from the MCP server)
toolsFetchedAtstring | nullWhen the list of tools was last fetched (ISO 8601). Set even when the fetch returned 0 tools. null if it has never been fetched

Response Example​

JSON
{
"kind": "mcp",
"connectionId": "12",
"name": "Internal document search",
"requiresLogin": false,
"tools": [
{
"name": "search_documents",
"displayName": "Document search",
"description": "Searches internal documents by keyword",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string"
}
},
"required": [
"query"
]
},
"outputSchema": null,
"declaredAnnotations": {
"readOnlyHint": true
},
"presentInLastFetch": true
}
],
"toolsFetchedAt": "2026-11-17T09:30:00.000Z"
}

Error Responses​

StatuscodeDescription
400invalid_parameterconnectionId is not a positive integer of up to 16 digits, or projectId is not a UUID
403forbiddenCalled with a system integration token
403sso_requiredWith projectId, the user record is not linked to an account of the authorization server
404connector_not_foundThe connector does not exist, is disabled, or cannot be used by the organization and job type
404project_not_foundThe project in projectId does not exist, or you are not a member of it or a person with the organization operations role

GET/v1/connectors/a2a/{connectionId}

Gets an A2A connector and its agent card. The agent card is the one saved in the admin console.

Path Parameters​

パラメータ型必須説明
connectionIdstring必須Connector ID (a positive integer of up to 16 digits)

Request Example​

Get A2A connector
1curl https://<your-domain>/api/v1/connectors/a2a/7 \
2-H "Authorization: Bearer <access_token>"

Response Fields (200 OK)​

FieldTypeDescription
kindstring"a2a"
connectionIdstringConnector ID
namestring | nullConnector name
requiresLoginbooleanWhether you must sign in on the project screen before using the connector
agentCardobjectAgent card
agentCard.descriptionstring | nullDescription
agentCard.versionstring | nullVersion
agentCard.providerobject | nullProvider
agentCard.skillsarraySkills
agentCard.capabilitiesobject | nullSupported capabilities
agentCard.defaultInputModesarrayAccepted formats
agentCard.defaultOutputModesarrayReturned formats
agentCard.supportedInterfacesarraySupported connection methods
agentCard.documentationUrlstring | nullDocumentation URL
agentCard.iconUrlstring | nullIcon URL
agentCard.securitySchemesobject | nullHow to authenticate to the agent (as the agent publishes it)
agentCard.securityRequirementsarrayAuthentication requirements (as the agent publishes them)

The contents of provider, skills, capabilities, and supportedInterfaces in agentCard are in the form the other agent publishes.

Response Example​

JSON
{
"kind": "a2a",
"connectionId": "7",
"name": "Translation Agent",
"requiresLogin": false,
"agentCard": {
"description": "Translates documents into the specified language",
"version": "1.0.0",
"provider": {
"organization": "Example Corp.",
"url": "https://example.com"
},
"skills": [
{
"id": "translate",
"name": "Translation",
"description": "Translates documents",
"tags": [
"translation"
]
}
],
"capabilities": {
"streaming": true
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain"
],
"supportedInterfaces": [
{
"url": "https://agent.example.com/a2a",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"documentationUrl": null,
"iconUrl": null,
"securitySchemes": null,
"securityRequirements": []
}
}

Error Responses​

StatuscodeDescription
400invalid_parameterconnectionId is not a positive integer of up to 16 digits
403forbiddenCalled with a system integration token
404connector_not_foundThe connector does not exist or is disabled

Execution Conversations​

Read the conversation with the Agent during an execution (the request to the Agent, explanations along the way, the final response, and so on) with GET /v1/conversations/{conversationId}/messages of the conversation API. For details, see Conversation Management in the User API Reference (Conversations, Organizations).

  • You can find conversationId in conversationId of the execution history and the execution result.
  • Only the owner of the project at the time of the execution (the person the execution runs as) can read it, because project executions run in the owner's name. Conversations of executions from before the ownership was transferred are read by the previous owner (see Who decides what). Other owners, operators and members get 404 Not Found. It cannot be read from a system integration.
  • An execution of a workflow step run by a registered Agent has no conversation (conversationId is null). For periodic sweeps of a cycle, the messages of each round are added to one conversation per placement and step. Because the conversation API does not link messages to executions, identify them by the messages whose sender is "User" (the request to the Agent for that round) around the start time of the execution (startedAt).

Error Responses​

HTTP Status Codes​

HTTP status codes that may be returned by all endpoints.

StatusDescription
400 Bad RequestInvalid request parameters
401 UnauthorizedToken is invalid or missing. Also returned for a token of a user whose use was suspended by an administrator (see "Suspended users" below)
403 ForbiddenNo access permission to the resource
404 Not FoundResource does not exist, or the path or method is not defined (405 is not returned)
409 ConflictOperation conflict, such as the resource currently being processed
409 ConflictA person with the organization operations role (the "Operator" role assigned in "Admin Roles" in the admin console) who does not take part in the project called an operation that role cannot use (error.code is forbidden_role). It does not clear by waiting. For an owner-only operation, ask an owner of the project to do it. For other operations, ask an owner to add you to the project; you can then call them as your project role allows
413 Payload Too LargeRequest body exceeds the size limit
415 Unsupported Media TypeThe request body format (Content-Type) is not supported
429 Too Many RequestsRate limit or concurrent-run limit exceeded. error.type is rate_limit_error, and error.code depends on the endpoint (for example monthly_quota_exceeded for the monthly limit and too_many_active_runs for concurrent project runs). Please wait and retry.
500 Internal Server ErrorInternal server error
502 Bad GatewayCommunication error with upstream services (authentication / chat backends, etc.)
503 Service UnavailableService temporarily unavailable
504 Gateway TimeoutUpstream service response timeout

Error Response Format​

All error responses are returned in the following common structure.

FieldTypeDescription
error.typestringError classification. One of: "invalid_request_error", "authentication_error", "insufficient_scope_error", "forbidden_error", "not_found_error", "conflict_error", "payload_too_large_error", "rate_limit_error", "server_error", "upstream_error"
error.messagestringHuman-readable error message
error.codestringMachine-processable error code (e.g., "missing_parameter", "invalid_parameter", "invalid_token")
error.paramstringThe parameter that caused the error. Included only for validation errors
error.reasonstringThe kind of reason for the refusal. Included only for 409 (definition_invalid) of the project APIs
error.suggested_actionstringRecommended action to take. Included only for some errors
JSON
{
"error": {
"type": "invalid_request_error",
"message": "Invalid parameter: limit",
"code": "invalid_parameter",
"param": "limit",
"suggested_action": "limit must be between 1 and 100"
}
}

Suspended users​

A call with the token of a user whose use was suspended by an administrator returns 401 Unauthorized. error.code is account_suspended.

The following APIs do not check whether the user is suspended: GET /v1/organizations, GET /v1/job-types, GET /v1/user, PATCH /v1/user, GET /v1/marketplace-agents, the MCP tools list_agents and cancel_chat (when no task is in progress), and the Agent Card of a registered Agent (GET /api/v1/a2a/agents/{agentId}/.well-known/agent-card.json).