Authentication
Create a key in your workspace under Settings → API. The full secret is shown once, at creation, and never again — we store only a hash of it. Send it as a bearer token on every request:
Authorization: Bearer hh_live_...A key belongs to one workspace, and every request is scoped to that workspace’s data. Keys carry scopes; a request needing a scope the key doesn’t have is rejected rather than silently downgraded.
| Scope | Grants |
|---|---|
| read | List agents and read the work they produced. |
| run | Trigger an agent's jobs. |
| manage | Hire, configure and teach agents. Changes what the workspace is billed. |
| approve | Decide review-queue items on the owner's behalf — this replaces their own sign-off, so it is off by default and granted deliberately. |
Revoking a key takes effect immediately. Keys keep working across plan changes but stop at the billing gate if a workspace’s subscription lapses, so a lapsed account can still read its data but cannot spend.
Rate limits and budgets
Runs are subject to the same per-workspace burst limit and monthly budget cap as the dashboard. A request over either returns 429 with a reason you can show your own users.
Endpoints
GET /api/v1/agents
List the agents in your workspace. Requires the read scope.
Returns: agents[].id, name, status, templateSlug, health, lastRunAt, createdAt.
GET /api/v1/outputs
List the work your agents produced — drafts, escalations, leads, digests — newest first. Requires the read scope.
| Query parameter | Type | Notes |
|---|---|---|
| agentId | string | Only this agent's output. |
| status | pending | approved | dismissed | Where the item sits in the review queue. |
| limit | 1–200 | Page size. Defaults to 50. |
| before | ISO 8601 datetime | Keyset cursor — pass the previous page's nextCursor. |
Returns: outputs[].id, agentId, workflow, type, title, content, status, createdAt, nextCursor.
POST /api/v1/agents/{id}/run
Send one message to an agent and get its answer, from your own backend. Requires the run scope.
| Body field | Type | Notes |
|---|---|---|
| message | string, 1–4000 chars | Required. |
| history | array of { role, content }, max 20 | Prior turns, so the agent has the thread. |
Returns: answer, effects.
An example
curl https://hiredhands.dev/api/v1/outputs?status=pending \
-H "Authorization: Bearer hh_live_..."
curl -X POST https://hiredhands.dev/api/v1/agents/AGENT_ID/run \
-H "Authorization: Bearer hh_live_..." \
-H "Content-Type: application/json" \
-d '{"message":"Where is order 1042?"}'Errors
Every error is a JSON body with an error string. 401 means the key is missing, malformed or revoked; 403 means it lacks the scope; 404 means the agent isn’t in this workspace; 429 is a rate limit or a budget cap.
Want a callback instead of polling? Use webhooks.