Agents

Agents are rows in users with user_type='agent' (source of truth — not agent_users). All agent endpoints are admin-scoped.

Acting context (agent API keys)

actor_user_id = agent user id (stamped on user_created_by / note user_email)
effective_user_id = users.reports_to_user_id human manager when set; otherwise the agent id
Org ACL uses effective user; write stamps use actor

Additive migration: migrations/2026_09_17_001_users_reports_to_user_id.sql. Until applied, create-agent still requires reports_to_user_id but persistence of the column is skipped when absent.

Quickstart

Base URL (canonical)

https://api.strackerapp.com/v1/

Same gateway also answers under /api/v1 on strackerapp.com. Prefer the api. subdomain. Do not use api.stracker.io (not wired; returns 403).

Environments (keep separate)

Env	Base	Keys
Production	`https://api.strackerapp.com/v1`	`sk_prod_…` only
Local smoke	`http://127.0.0.1:8888/api/v1`	`sk_dev_…` only

Never mix prod keys with local, or local keys with prod.

Auth (all endpoints)

Org-scoped Bearer API key. Agent keys act as the agent with reports_to ACL inheritance.

Authorization: Bearer sk_REPLACE
Content-Type: application/json

# Optional alternate header:
# X-Stracker-Api-Key: sk_REPLACE

Response envelope

{
  "success": true,
  "data":   { /* endpoint-specific payload */ }
}

Errors

Failed responses always have success: false and an error object with a stable code and a human-readable message:

{
  "success": false,
  "error": {
    "code":    "VALIDATION_ERROR",
    "message": "company_name is required"
  }
}

HTTP status	When	What to do
`400`	Validation failed (missing required fields, bad enum, migration not applied for company/contact notes, assignee not in org, slot unavailable).	Read `error.message`; fix the payload.
`401`	Missing or invalid `Authorization` / `X-Stracker-Api-Key`.	Check the API key; confirm the header is present.
`403`	Key is valid but lacks permission (e.g. non-admin calling agent admin endpoints), or org scope mismatch.	Use an org-admin key, or confirm the resource belongs to the key's org.
`404`	Resource not found or not visible to this org.	Verify the id and org scoping.
`500`	Unexpected server error.	Retry with backoff; report if persistent.

Agents

Endpoints at a glance

Action	Method + Path	Summary
List agents	`GET /agents`	List agent users in the org (admin).
Get an agent	`GET /agents/{id}`	Get an agent including reports_to (admin).
Create an agent	`POST /agents`	Create an agent. Required: display_name, reports_to_user_id (human in same org).
Create agent credential	`POST /agents/{id}/credentials`	Create an API credential for an agent (admin). Returns the secret once.
Rotate agent credential	`POST/PUT /agents/{id}/credentials/rotate`	Rotate an agent's API credential (admin).
Reveal agent credential	`GET /agents/{id}/credentials/{keyId}/reveal`	Reveal an agent credential secret by key id (admin; audit-logged).
Mint agent UI token	`POST /agents/{id}/token/mint`	Mint a UI login token for an agent (admin).
Revoke agent UI token	`POST /agents/{id}/token/revoke`	Revoke a UI login token for an agent (admin).

GET `/agents`

List agent users in the org (admin).

Query parameters

Field	Type	Required	Description
`q`	`string`	no	Search display name
`limit`	`integer`	no	Page size Default: `50`.
`offset`	`integer`	no	Offset

Request example

curl -sS "https://api.strackerapp.com/v1/agents?limit=5" \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": {
    "agents": [
      { "id": 200, "display_name": "Smoke Agent", "user_type": "agent", "reports_to_user_id": 9 }
    ]
  }
}

GET `/agents/{id}`

Get an agent including reports_to (admin).

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id

Request example

curl -sS https://api.strackerapp.com/v1/agents/200 \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": {
    "agent": {
      "id": 200,
      "display_name": "Smoke Agent",
      "reports_to_user_id": 9,
      "reports_to": { "id": 9, "name": "Alex Manager", "email": "[email protected]" }
    }
  }
}

POST `/agents`

Create an agent. Required: display_name, reports_to_user_id (human in same org).

Body parameters

Field	Type	Required	Description
`display_name`	`string`	yes	Agent display name
`reports_to_user_id`	`integer`	yes	Human manager users.id in same org

Request example

curl -sS https://api.strackerapp.com/v1/agents \
  -H "Authorization: Bearer sk_REPLACE" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Smoke Agent","reports_to_user_id":123}'

Response `201 Created`

{
  "success": true,
  "data": {
    "agent": { "id": 201, "display_name": "Smoke Agent", "reports_to_user_id": 123 }
  }
}

POST `/agents/{id}/credentials`

Create an API credential for an agent (admin). Returns the secret once.

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id

Body parameters

Field	Type	Required	Description
`label`	`string`	no	Optional label

Request example

curl -sS https://api.strackerapp.com/v1/agents/200/credentials \
  -H "Authorization: Bearer sk_REPLACE" \
  -H "Content-Type: application/json" \
  -d '{"label":"default"}'

Response `201 Created`

{
  "success": true,
  "data": {
    "credential": { "id": 12, "label": "default", "api_key": "sk_prod_…" }
  }
}

POST PUT `/agents/{id}/credentials/rotate`

Rotate an agent's API credential (admin).

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id

Request example

curl -sS -X POST https://api.strackerapp.com/v1/agents/200/credentials/rotate \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": {
    "credential": { "id": 13, "api_key": "sk_prod_…" }
  }
}

GET `/agents/{id}/credentials/{keyId}/reveal`

Reveal an agent credential secret by key id (admin; audit-logged).

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id
`keyId`	`integer`	yes	Credential key id

Request example

curl -sS https://api.strackerapp.com/v1/agents/200/credentials/12/reveal \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": {
    "credential": { "id": 12, "api_key": "sk_prod_…" }
  }
}

POST `/agents/{id}/token/mint`

Mint a UI login token for an agent (admin).

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id

Request example

curl -sS -X POST https://api.strackerapp.com/v1/agents/200/token/mint \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": {
    "token": "…",
    "expires_at": "2026-09-19T00:00:00Z"
  }
}

POST `/agents/{id}/token/revoke`

Revoke a UI login token for an agent (admin).

Path parameters

Field	Type	Required	Description
`id`	`integer`	yes	Agent user id

Request example

curl -sS -X POST https://api.strackerapp.com/v1/agents/200/token/revoke \
  -H "Authorization: Bearer sk_REPLACE"

Response `200 OK`

{
  "success": true,
  "data": { "revoked": true }
}

Agents

Acting context (agent API keys)

Quickstart

Response envelope

Errors

Agents

Endpoints at a glance

GET /agents

Query parameters

Request example

Response 200 OK

GET /agents/{id}

Path parameters

Request example

Response 200 OK

POST /agents

Body parameters

Request example

Response 201 Created

POST /agents/{id}/credentials

Path parameters

Body parameters

Request example

Response 201 Created

POST PUT /agents/{id}/credentials/rotate

Path parameters

Request example

Response 200 OK

GET /agents/{id}/credentials/{keyId}/reveal

Path parameters

Request example

Response 200 OK

POST /agents/{id}/token/mint

Path parameters

Request example

Response 200 OK

POST /agents/{id}/token/revoke

Path parameters

Request example

Response 200 OK

GET `/agents`

Response `200 OK`

GET `/agents/{id}`

Response `200 OK`

POST `/agents`

Response `201 Created`

POST `/agents/{id}/credentials`

Response `201 Created`

POST PUT `/agents/{id}/credentials/rotate`

Response `200 OK`

GET `/agents/{id}/credentials/{keyId}/reveal`

Response `200 OK`

POST `/agents/{id}/token/mint`

Response `200 OK`

POST `/agents/{id}/token/revoke`

Response `200 OK`