Run an agent

POST

/api/v3/agents/{agentUuid}/runs

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/agents/example/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "resourceUniqueId": "35f725edbi" }'

• Production

Run an agent against a resource — currently a letter — identified by resourceUniqueId. Returns the created run.

Authorizations

• bearerAuth

Parameters

Path Parameters

agentUuid

required

string

The agent’s unique identifier.

Request Body ^required

Media type application/json

object

api

required

Required. Set to true to authenticate with an API key.

boolean

resourceUniqueId

required

The unique identifier of the resource to run the agent against — currently a letter.

string

Example

{
  "api": true,
  "resourceUniqueId": "35f725edbi"
}

Responses

201

201 Created

Media type application/json

object

items

object

uniqueId

string

agentUniqueId

string

agentName

string

agentType

integer

letterTitle

string

contextLabel

string

resourceType

integer

resourceUniqueId

string

status

integer

summary

string

nullable

validationCode

integer

dispatchedAt

string

nullable

startedAt

string

nullable

completedAt

string

nullable

judgments

Array<object>

object

uniqueId

string

severity

integer

confidence

integer

category

string

finding

string

suggestion

string

state

integer

createdAt

string

updatedAt

string

isOutdated

boolean

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": {
    "uniqueId": "vq5rnof1op",
    "agentUniqueId": "mofuehvagv",
    "agentName": "House style checker",
    "agentType": 0,
    "letterTitle": "This week in the daily",
    "contextLabel": "the-daily",
    "resourceType": 0,
    "resourceUniqueId": "35f725edbi",
    "status": 0,
    "summary": null,
    "validationCode": 200,
    "dispatchedAt": null,
    "startedAt": null,
    "completedAt": null,
    "judgments": [],
    "createdAt": "2026-06-18T14:22:03+00:00",
    "updatedAt": "2026-06-18T14:22:03+00:00"
  },
  "message": "",
  "total": 10
}