Agent API

To start agent runs from your own systems, use these REST endpoints with an API key. You can list your agents, start a run, poll for the result or have it posted back to you. No MCP client is needed.

Authentication

Every endpoint needs an API key as a Bearer token. Create keys on the API keys page in your dashboard.

Authorization: Bearer YOUR_API_KEY

Endpoints

List your agents

curl 'https://app.tirelesscrew.com/api/v1/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "agents": [
    {
      "id":                  "018f…",
      "name":                "Abandoned Cart Recovery",
      "description":         "Sends personalised recovery emails…",
      "run_url":             "https://app.tirelesscrew.com/api/v1/agents/018f…/run",
      "ready":               true,
      "missing_connections": [],
      "input_guidance":      "Sends personalised recovery emails…"
    }
  ]
}

When ready is false, missing_connections names the tools that still need one of your accounts connected before the agent can run.

Start a run

curl -X POST 'https://app.tirelesscrew.com/api/v1/agents/AGENT_ID/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-12345-retry-1' \
  -d '{
    "input": "Process abandoned cart for customer [email protected], cart total $89.99"
  }'

Response (202):

{
  "run_id":     "019a…",
  "status":     "pending",
  "status_url": "https://app.tirelesscrew.com/api/v1/runs/019a…"
}

With files

Upload files as multipart run_files[] fields. Accepted types are PDF, CSV, TXT, JSON, XML, XLSX, DOCX, PNG, JPG and WebP.

curl -X POST 'https://app.tirelesscrew.com/api/v1/agents/AGENT_ID/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'input=Process the attached invoice' \
  -F 'run_files[]=@/path/to/invoice.pdf'

Or pass the addresses of publicly reachable files in file_urls:

curl -X POST 'https://app.tirelesscrew.com/api/v1/agents/AGENT_ID/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "input":     "Summarise this document",
    "file_urls": ["https://example.com/report.pdf"]
  }'

With a callback

Pass callback_url to receive a POST when the run finishes, whether it completed or failed. It must be a public HTTPS address; private and internal addresses are refused.

curl -X POST 'https://app.tirelesscrew.com/api/v1/agents/AGENT_ID/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "input":        "Run the weekly report",
    "callback_url": "https://your-app.example.com/webhooks/agent-done"
  }'

The callback body:

{
  "run_id":   "019a…",
  "agent_id": "018f…",
  "status":   "completed",
  "output":   "Weekly report: 42 orders processed…",
  "error":    null,
  "cost_usd": 0.0012
}

When the run failed, output is null and error holds a plain-language message. Your endpoint has 10 seconds to answer. A failed callback is not retried, so keep polling the run as a fallback.

Idempotency

To retry a run request safely, send an Idempotency-Key header. The same key returns the original run_id for 24 hours instead of starting another run, and two requests that arrive at the same moment with the same key start only one.

Poll for the result

curl 'https://app.tirelesscrew.com/api/v1/runs/RUN_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Poll every few seconds until status is completed, failed or cancelled. While the run is going, output, completed_at and cost_usd are null:

{
  "run_id":       "019a…",
  "agent_id":     "018f…",
  "status":       "running",
  "started_at":   "2026-07-17T10:00:00+00:00",
  "completed_at": null,
  "output":       null,
  "error":        null,
  "cost_usd":     null
}

When it is complete:

{
  "run_id":       "019a…",
  "agent_id":     "018f…",
  "status":       "completed",
  "started_at":   "2026-07-17T10:00:00+00:00",
  "completed_at": "2026-07-17T10:00:14+00:00",
  "output":       "Weekly report: 42 orders processed…",
  "error":        null,
  "cost_usd":     0.0012
}

Start a run by email

An agent can also start a run when an email arrives at agent+{token}@{domain}. This works only when inbound email is set up on the platform and the agent’s email trigger is on. Contact support to have it switched on.

The run input contains the sender’s address, the subject and the new part of the message, with quoted history and common signatures removed. Treat the sender address as unverified. Attachments go through the same checks as other run files (size, type, number per run and your storage quota); an attachment that fails them is skipped, and a note in the run input says so. Replies in the same email thread continue the same conversation with the agent.

To prevent mail loops, automatic replies and mail marked as bulk, junk or auto-reply are refused. A message ID is accepted once in 24 hours, each agent address takes up to 30 messages a minute, and mail to an unknown address is dropped without a bounce.

Run through a seat

If you use organizations, each seat in your organization chart has its own API address. A run started through a seat goes to whichever agent fills that seat at the time, so changing the agent does not change the address.

The run endpoint takes the same input, file_urls, run_files[], callback_url and Idempotency-Key as an agent run, and you poll it with the same GET /api/v1/runs/{id}. An idempotency key belongs to the seat, not the agent, so replaying it after you change the agent starts a new run. Request and response examples are on Organization seats.

Errors