Skip to navigation
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.

persona_idslist of strings or nullOptional

Persona UUIDs to analyze against, max 3. Used by: persona. Send this or persona_id, not both. Retrieve valid IDs from GET /personas.

no_personasbooleanOptionalDefaults to false

Review the document without any reader’s perspective. Set this when no persona was chosen on purpose; leave it unset to let the review pick the readers a document is written for. Cannot be sent with persona_ids.

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.
issueslist of maps from strings to any or nullOptional

Issues from a previous run to act on, each exactly as returned in that run’s result. Supported by agents that apply or rework existing findings; when provided, such an agent works from these instead of re-detecting. Positions must refer to the text in this request. Other agents ignore this field.

generate_fixesboolean or nullOptional

When true, agents that apply existing findings also draft a fix for findings that carry no suggested replacement. Every drafted fix is verified in context before it is applied; a finding whose draft fails that verification is returned unapplied and its text is left unchanged. Off by default. Other agents ignore this field.

lenseslist of enums or nullOptionalDeprecated

Deprecated and ignored. A review selects its own agents server-side from the organization’s enabled agents.

Allowed values:

Response

Successful Response
workflow_idstring
Workflow ID for tracking
statusenum
Workflow status
Allowed values:
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.

Allowed values:
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