API Reference

Auto-generated

Agent

API reference for agent endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

POST /api/v1/agent/feedback

POST

/api/v1/agent/feedback

Submit Agent Feedback

Parameters

Name	Type	Required	Description
what_tried	`string`	Optional	what_tried
what_failed	`string`	Required	What went wrong — the core signal used to cluster reports.
what_expected	`string`	Optional	what_expected
category	`"blocked" \| "wrong_result" \| "confusing" \| "slow" \| "pricing" \| "suggestion" \| "other"`	Optional	category
suggestion	`string`	Optional	suggestion
tool_name	`string`	Optional	tool_name
job_id	`string`	Optional	job_id
surface	`"mcp" \| "api_hint" \| "sdk" \| "setup"`	Optional	surface
url	`string`	Optional	url
dry_run	`boolean`	Optional	Only return up to 3 matching clusters; nothing is stored and no ticket is filed.Default: `False`
same_as	`string`	Optional	same_as
new	`boolean`	Optional	File as a new report even when a close match exists.Default: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/feedback \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "what_failed": "example_what_failed"
  }'

Response Example

JSON

{
  "report_id": "example",
  "cluster_key": "example",
  "status": "example",
  "message": "example",
  "status_url": "example",
  "ticket_ref": "example"
}

POST /api/v1/agent/feedback/batch

POST

/api/v1/agent/feedback/batch

Submit Agent Feedback Batch

Parameters

Name	Type	Required	Description
reports	`object[]`	Required	Reports

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/feedback/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reports": []
  }'

Response Example

JSON

{
  "results": [],
  "filed_anonymously": true,
  "anonymous_reason": "example"
}

GET /api/v1/agent/feedback/{cluster_key}

GET

/api/v1/agent/feedback/{cluster_key}

Get Agent Feedback Status

Parameters

Name	Type	Required	Description
cluster_key	`string`	Required	cluster_key

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/feedback/<cluster_key> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "report_id": "example",
  "cluster_key": "example",
  "status": "example",
  "report_count": 0,
  "linked_github_issue": "example",
  "fixed_in": "example"
}

GET /api/v1/agent/issues

GET

/api/v1/agent/issues

List Agent Issues

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/issues \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "issues": [],
  "total": 0
}

POST /api/v1/agent/issues/{cluster_key}/vote

POST

/api/v1/agent/issues/{cluster_key}/vote

Vote Agent Issue

Parameters

Name	Type	Required	Description
cluster_key	`string`	Required	cluster_key

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/issues/<cluster_key>/vote \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "cluster_key": "example",
  "vote_count": 0,
  "status": "example"
}

POST /api/v1/agent/keys

POST

/api/v1/agent/keys

Mint the one API key an OAuth grant was approved to create

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/keys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key": "example",
  "key_delivered": true,
  "key_prefix": "example",
  "name": "example",
  "scopes": [],
  "spend_cap_usd": 0
}

POST /api/v1/agent/signup

POST

/api/v1/agent/signup

Start an agent signup that a human must approve

Parameters

Name	Type	Required	Description
email	`string`	Optional	email
agent_name	`string`	Required	Agent Name
agent_url	`string`	Optional	agent_url
requested_scopes	`string[]`	Optional	Requested Scopes

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "example_agent_name"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/agent/signup/by-code/{user_code}

GET

/api/v1/agent/signup/by-code/{user_code}

Show a pending agent signup to the signed-in human

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code> \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_code": "example",
  "agent_name": "example",
  "agent_url": "example",
  "verified_agent": true,
  "agent_identity": "example",
  "email": "example"
}

POST /api/v1/agent/signup/by-code/{user_code}/approve

POST

/api/v1/agent/signup/by-code/{user_code}/approve

Approve a pending agent signup (signed-in human)

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code>/approve \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example"
}

POST /api/v1/agent/signup/by-code/{user_code}/deny

POST

/api/v1/agent/signup/by-code/{user_code}/deny

Deny a pending agent signup (signed-in human)

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code>/deny \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example"
}

GET /api/v1/agent/signup/pending

GET

/api/v1/agent/signup/pending

List agent requests waiting for the signed-in human

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/pending \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "requests": []
}

GET /api/v1/agent/signup/{signup_id}

GET

/api/v1/agent/signup/{signup_id}

Poll an agent signup; returns the scoped API key once after approval

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/<signup_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example",
  "api_key": "example",
  "key_prefix": "example",
  "scopes": "example",
  "permissions": "example",
  "spend_cap_usd": "example"
}

POST /api/v1/agent/signup/{signup_id}/ack

POST

/api/v1/agent/signup/{signup_id}/ack

Confirm the key is stored; drops the redelivery copy immediately

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id
delivery_id	`string`	Required	Delivery Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/<signup_id>/ack \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_id": "example_delivery_id"
  }'

Response Example

JSON

{
  "acknowledged": true
}

POST /api/v1/agent/signup/{signup_id}/renew

POST

/api/v1/agent/signup/{signup_id}/renew

Renew a pending agent signup once for a fresh approval window

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/<signup_id>/renew \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example",
  "api_key": "example",
  "key_prefix": "example",
  "scopes": "example",
  "permissions": "example",
  "spend_cap_usd": "example"
}

POST /api/v1/agent/support-ticket

POST

/api/v1/agent/support-ticket

Create Agent Support Ticket

Parameters

Name	Type	Required	Description
subject	`string`	Required	Short ticket title.
body	`string`	Required	What the user needs help with.
category_slug	`string`	Optional	category_slug
on_behalf_of_user	`boolean`	Optional	True when the agent files this because its user asked for help.Default: `True`
tool_name	`string`	Optional	tool_name
job_id	`string`	Optional	job_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/support-ticket \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "example_subject",
    "body": "example_body",
    "on_behalf_of_user": false
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/agent/trial

POST

/api/v1/agent/trial

Issue a zero-signup agent trial token

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/agent/trial/claim

POST

/api/v1/agent/trial/claim

Claim a trial key into your account (signed-in human)

Parameters

Name	Type	Required	Description
token	`string`	Required	The 't' value from the claim link ('https://alterlab.io/claim?t=...').

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial/claim \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "example_token"
  }'

Response Example

JSON

{
  "status": "example",
  "key": "example",
  "key_name": "example",
  "dashboard_url": "example",
  "message": "example"
}

POST /api/v1/agent/trial/claim/preview

POST

/api/v1/agent/trial/claim/preview

Preview a trial claim link (signed-in human)

Parameters

Name	Type	Required	Description
token	`string`	Required	The 't' value from the claim link ('https://alterlab.io/claim?t=...').

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial/claim/preview \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "example_token"
  }'

Response Example

JSON

{
  "status": "example",
  "created_at": "example",
  "trial_expired": true,
  "claim_expires_at": "example",
  "scopes": [],
  "daily_spend_cap_usd": 0
}

Last updated: June 2026

API Reference

Auto-generated

Agent

API reference for agent endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

POST /api/v1/agent/feedback

POST

/api/v1/agent/feedback

Submit Agent Feedback

Parameters

Name	Type	Required	Description
what_tried	`string`	Optional	what_tried
what_failed	`string`	Required	What went wrong — the core signal used to cluster reports.
what_expected	`string`	Optional	what_expected
category	`"blocked" \| "wrong_result" \| "confusing" \| "slow" \| "pricing" \| "suggestion" \| "other"`	Optional	category
suggestion	`string`	Optional	suggestion
tool_name	`string`	Optional	tool_name
job_id	`string`	Optional	job_id
surface	`"mcp" \| "api_hint" \| "sdk" \| "setup"`	Optional	surface
url	`string`	Optional	url
dry_run	`boolean`	Optional	Only return up to 3 matching clusters; nothing is stored and no ticket is filed.Default: `False`
same_as	`string`	Optional	same_as
new	`boolean`	Optional	File as a new report even when a close match exists.Default: `False`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/feedback \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "what_failed": "example_what_failed"
  }'

Response Example

JSON

{
  "report_id": "example",
  "cluster_key": "example",
  "status": "example",
  "message": "example",
  "status_url": "example",
  "ticket_ref": "example"
}

POST /api/v1/agent/feedback/batch

POST

/api/v1/agent/feedback/batch

Submit Agent Feedback Batch

Parameters

Name	Type	Required	Description
reports	`object[]`	Required	Reports

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/feedback/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reports": []
  }'

Response Example

JSON

{
  "results": [],
  "filed_anonymously": true,
  "anonymous_reason": "example"
}

GET /api/v1/agent/feedback/{cluster_key}

GET

/api/v1/agent/feedback/{cluster_key}

Get Agent Feedback Status

Parameters

Name	Type	Required	Description
cluster_key	`string`	Required	cluster_key

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/feedback/<cluster_key> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "report_id": "example",
  "cluster_key": "example",
  "status": "example",
  "report_count": 0,
  "linked_github_issue": "example",
  "fixed_in": "example"
}

GET /api/v1/agent/issues

GET

/api/v1/agent/issues

List Agent Issues

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/issues \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "issues": [],
  "total": 0
}

POST /api/v1/agent/issues/{cluster_key}/vote

POST

/api/v1/agent/issues/{cluster_key}/vote

Vote Agent Issue

Parameters

Name	Type	Required	Description
cluster_key	`string`	Required	cluster_key

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/issues/<cluster_key>/vote \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "cluster_key": "example",
  "vote_count": 0,
  "status": "example"
}

POST /api/v1/agent/keys

POST

/api/v1/agent/keys

Mint the one API key an OAuth grant was approved to create

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/keys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key": "example",
  "key_delivered": true,
  "key_prefix": "example",
  "name": "example",
  "scopes": [],
  "spend_cap_usd": 0
}

POST /api/v1/agent/signup

POST

/api/v1/agent/signup

Start an agent signup that a human must approve

Parameters

Name	Type	Required	Description
email	`string`	Optional	email
agent_name	`string`	Required	Agent Name
agent_url	`string`	Optional	agent_url
requested_scopes	`string[]`	Optional	Requested Scopes

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "example_agent_name"
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/agent/signup/by-code/{user_code}

GET

/api/v1/agent/signup/by-code/{user_code}

Show a pending agent signup to the signed-in human

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code> \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_code": "example",
  "agent_name": "example",
  "agent_url": "example",
  "verified_agent": true,
  "agent_identity": "example",
  "email": "example"
}

POST /api/v1/agent/signup/by-code/{user_code}/approve

POST

/api/v1/agent/signup/by-code/{user_code}/approve

Approve a pending agent signup (signed-in human)

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code>/approve \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example"
}

POST /api/v1/agent/signup/by-code/{user_code}/deny

POST

/api/v1/agent/signup/by-code/{user_code}/deny

Deny a pending agent signup (signed-in human)

Parameters

Name	Type	Required	Description
user_code	`string`	Required	user_code

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/by-code/<user_code>/deny \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example"
}

GET /api/v1/agent/signup/pending

GET

/api/v1/agent/signup/pending

List agent requests waiting for the signed-in human

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/pending \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "requests": []
}

GET /api/v1/agent/signup/{signup_id}

GET

/api/v1/agent/signup/{signup_id}

Poll an agent signup; returns the scoped API key once after approval

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/agent/signup/<signup_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example",
  "api_key": "example",
  "key_prefix": "example",
  "scopes": "example",
  "permissions": "example",
  "spend_cap_usd": "example"
}

POST /api/v1/agent/signup/{signup_id}/ack

POST

/api/v1/agent/signup/{signup_id}/ack

Confirm the key is stored; drops the redelivery copy immediately

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id
delivery_id	`string`	Required	Delivery Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/<signup_id>/ack \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_id": "example_delivery_id"
  }'

Response Example

JSON

{
  "acknowledged": true
}

POST /api/v1/agent/signup/{signup_id}/renew

POST

/api/v1/agent/signup/{signup_id}/renew

Renew a pending agent signup once for a fresh approval window

Parameters

Name	Type	Required	Description
signup_id	`string`	Required	signup_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/signup/<signup_id>/renew \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "example",
  "api_key": "example",
  "key_prefix": "example",
  "scopes": "example",
  "permissions": "example",
  "spend_cap_usd": "example"
}

POST /api/v1/agent/support-ticket

POST

/api/v1/agent/support-ticket

Create Agent Support Ticket

Parameters

Name	Type	Required	Description
subject	`string`	Required	Short ticket title.
body	`string`	Required	What the user needs help with.
category_slug	`string`	Optional	category_slug
on_behalf_of_user	`boolean`	Optional	True when the agent files this because its user asked for help.Default: `True`
tool_name	`string`	Optional	tool_name
job_id	`string`	Optional	job_id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/support-ticket \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "example_subject",
    "body": "example_body",
    "on_behalf_of_user": false
  }'

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/agent/trial

POST

/api/v1/agent/trial

Issue a zero-signup agent trial token

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/agent/trial/claim

POST

/api/v1/agent/trial/claim

Claim a trial key into your account (signed-in human)

Parameters

Name	Type	Required	Description
token	`string`	Required	The 't' value from the claim link ('https://alterlab.io/claim?t=...').

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial/claim \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "example_token"
  }'

Response Example

JSON

{
  "status": "example",
  "key": "example",
  "key_name": "example",
  "dashboard_url": "example",
  "message": "example"
}

POST /api/v1/agent/trial/claim/preview

POST

/api/v1/agent/trial/claim/preview

Preview a trial claim link (signed-in human)

Parameters

Name	Type	Required	Description
token	`string`	Required	The 't' value from the claim link ('https://alterlab.io/claim?t=...').

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/agent/trial/claim/preview \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "example_token"
  }'

Response Example

JSON

{
  "status": "example",
  "created_at": "example",
  "trial_expired": true,
  "claim_expires_at": "example",
  "scopes": [],
  "daily_spend_cap_usd": 0
}

Last updated: June 2026