Developer ReferenceAPI ReferenceAgents

Run Agent

Run an agent.

Use wait=true to block until the workflow completes (201 Created). Default (wait=false) returns immediately with 202 Accepted.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

agent_idstringRequired

Query parameters

waitbooleanOptionalDefaults to false

Request

This endpoint expects an object.
textstringRequired1-100000 characters
Document text to analyze.
agentslist of strings or nullOptional

Agent IDs to execute. Resolved to agent names server-side.

domain_idslist of strings or nullOptional
Terminology domain IDs.
document_refstring or nullOptional1-512 characters

Caller-provided document identifier for tracking across scans.

urlstring or nullOptional>=1 character
Document URL.
document_namestring or nullOptional>=1 character
Document name or title.
style_guide_idstring or nullOptional>=1 character

Style guide ID to check the document against. target_id is a deprecated alias for this field; send exactly one of the two names.

content_profile_idstring or nullOptional>=1 character

Language-service content profile ID for style checking.

goalstring or nullOptional1-500 characters
Document goal for agent recommendation.
persona_idstring or nullOptional>=1 character

Agent configuration UUID for persona selection. Used by: persona. Retrieve valid IDs from GET /personas.

voice_profile_idstring or nullOptional>=1 character

Agent configuration UUID for brand voice profile selection. Used by: brand_voice. Retrieve valid IDs from GET /brand-voice-profiles.

webhook_urlstring or nullOptionalformat: "uri"1-2083 characters
Optional webhook URL for async result delivery.

Response

Successful Response
workflow_idstring
Workflow ID for tracking
statusenum
Workflow status
started_atdatetime
Workflow start time
request_idstring or nullOptional
Request tracking ID
document_refstring or nullOptional

Caller-provided document identifier.

check_typeenumOptional

How this check is counted: ‘batch’ for a document checked as part of a batch, ‘interactive’ for a direct /run check.

assignedbooleanOptionalDefaults to true
Whether the check counts as authoring activity for an author.
batch_idstring or nullOptional

Owning batch id (agbw_<nanoid>); null unless this is a batch check.

resultmap from strings to any or nullOptional

Execution result (if completed)

completed_atdatetime or nullOptional
Workflow completion time
duration_secondsdouble or nullOptional
Execution duration

Errors

401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
500
Internal Server Error