Runs API

The Runs API starts a run on a ticket and returns what the run did. Use it to connect a tool that is not built in, or to start runs from your own code.

Authentication

Create a key under Settings, API keys and send it as a bearer token. Keys belong to a workspace and can be limited to chosen categories.

Start a run

1curl https://api.kestrel.example/v1/runs \2  -H "Authorization: Bearer $KESTREL_KEY" \3  -H "Content-Type: application/json" \4  -d '{ "ticket": "81226", "category": "refunds" }'

The call returns at once with the run's id. The work happens in the background.

1{2  "id": "run_48213",3  "status": "running",4  "ticket": "81226"5}

Read a run

curl https://api.kestrel.example/v1/runs/run_48213 \  -H "Authorization: Bearer $KESTREL_KEY"

A finished run lists every step with its time, the tool it used and the result.

1{2  "id": "run_48213",3  "status": "resolved",4  "outcome": "acted_alone",5  "steps": [6    { "did": "read_ticket", "seconds": 0.8 },7    { "did": "found_charge", "tool": "stripe", "seconds": 1.9 },8    { "did": "refunded", "amount": 4900, "seconds": 3.2 },9    { "did": "replied", "seconds": 0.6 }10  ]11}

Statuses

• running means the work is in progress.
• waiting means Kestrel asked a person and has not had an answer.
• resolved means the ticket is closed.
• handed_over means the ticket went to your team.

Limits

One hundred requests a minute for each key. A request over the limit gets a 429 with a Retry-After header.

To hear about a run without asking again and again, use Webhooks.