API Reference

Auto-generated

Keys

API reference for keys endpoints.

Auto-generated

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

POST /api/v1/api-keys/legacy-notice-shown

POST

/api/v1/api-keys/legacy-notice-shown

Mark Legacy Notice Shown

Request Example

Bash

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

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/api-keys/legacy-status

GET

/api/v1/api-keys/legacy-status

Get Legacy Keys Status

Request Example

Bash

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

Response Example

JSON

{
  "has_legacy_keys": true,
  "legacy_key_count": 0,
  "notice_shown": true
}

PATCH /api/v1/api-keys/{key_id}

PATCH

/api/v1/api-keys/{key_id}

Rename an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id
name	`string`	Required	New name for the API key

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/api-keys/<key_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name"
  }'

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "key_prefix": "example",
  "key": "example",
  "scopes": [],
  "created_at": "example"
}

GET /api/v1/api-keys/{key_id}/decrypt

GET

/api/v1/api-keys/{key_id}/decrypt

Decrypt an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "key": "example"
}

GET /api/v1/api-keys/{key_id}/limits

GET

/api/v1/api-keys/{key_id}/limits

Get Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "limits": "example",
  "has_limits": true
}

PUT /api/v1/api-keys/{key_id}/limits

PUT

/api/v1/api-keys/{key_id}/limits

Set Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
budget_limit_microcents	`integer`	Optional	budget_limit_microcents
request_limit	`integer`	Optional	request_limit
reset_period	`"daily" \| "weekly" \| "monthly"`	Optional	How often the counters reset.Default: `monthly`
enabled	`boolean`	Optional	Whether this limit is active.Default: `True`

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/api-keys/<key_id>/limits \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reset_period": "...",
    "enabled": false
  }'

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "limits": "example",
  "has_limits": true
}

DELETE /api/v1/api-keys/{key_id}/limits

DELETE

/api/v1/api-keys/{key_id}/limits

Delete Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/api-keys/<key_id>/limits \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/api-keys/{key_id}/regenerate

POST

/api/v1/api-keys/{key_id}/regenerate

Regenerate an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "key_prefix": "example",
  "key": "example",
  "scopes": [],
  "created_at": "example"
}

GET /api/v1/api-keys/{key_id}/usage

GET

/api/v1/api-keys/{key_id}/usage

Get Key Usage

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "total_requests": 0,
  "successful_requests": 0,
  "failed_requests": 0,
  "total_spend_microcents": 0
}

GET /api/v1/api-keys/{key_id}/usage/by-tier

GET

/api/v1/api-keys/{key_id}/usage/by-tier

Get Key Usage By Tier

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/by-tier \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "tiers": []
}

GET /api/v1/api-keys/{key_id}/usage/errors

GET

/api/v1/api-keys/{key_id}/usage/errors

Get Key Usage Errors

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/errors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "total_errors": 0,
  "errors": []
}

GET /api/v1/api-keys/{key_id}/usage/requests

GET

/api/v1/api-keys/{key_id}/usage/requests

Get Key Usage Requests

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
page	`integer`	Optional	Page number (1-based)Default: `1`
page_size	`integer`	Optional	Rows per pageDefault: `50`
status	`"success" \| "failed"`	Optional	Filter by request outcome
tier	`string`	Optional	Filter by tier_used value
domain	`string`	Optional	Substring match on extracted domain
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/requests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0,
  "items": []
}

GET /api/v1/api-keys/{key_id}/usage/timeseries

GET

/api/v1/api-keys/{key_id}/usage/timeseries

Get Key Usage Timeseries

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/timeseries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "granularity": "example",
  "data": []
}

Last updated: March 2026

API Reference

Auto-generated

Keys

API reference for keys endpoints.

Auto-generated

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

POST /api/v1/api-keys/legacy-notice-shown

POST

/api/v1/api-keys/legacy-notice-shown

Mark Legacy Notice Shown

Request Example

Bash

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

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/api-keys/legacy-status

GET

/api/v1/api-keys/legacy-status

Get Legacy Keys Status

Request Example

Bash

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

Response Example

JSON

{
  "has_legacy_keys": true,
  "legacy_key_count": 0,
  "notice_shown": true
}

PATCH /api/v1/api-keys/{key_id}

PATCH

/api/v1/api-keys/{key_id}

Rename an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id
name	`string`	Required	New name for the API key

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/api-keys/<key_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example_name"
  }'

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "key_prefix": "example",
  "key": "example",
  "scopes": [],
  "created_at": "example"
}

GET /api/v1/api-keys/{key_id}/decrypt

GET

/api/v1/api-keys/{key_id}/decrypt

Decrypt an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "key": "example"
}

GET /api/v1/api-keys/{key_id}/limits

GET

/api/v1/api-keys/{key_id}/limits

Get Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "limits": "example",
  "has_limits": true
}

PUT /api/v1/api-keys/{key_id}/limits

PUT

/api/v1/api-keys/{key_id}/limits

Set Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
budget_limit_microcents	`integer`	Optional	budget_limit_microcents
request_limit	`integer`	Optional	request_limit
reset_period	`"daily" \| "weekly" \| "monthly"`	Optional	How often the counters reset.Default: `monthly`
enabled	`boolean`	Optional	Whether this limit is active.Default: `True`

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/api-keys/<key_id>/limits \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reset_period": "...",
    "enabled": false
  }'

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "limits": "example",
  "has_limits": true
}

DELETE /api/v1/api-keys/{key_id}/limits

DELETE

/api/v1/api-keys/{key_id}/limits

Delete Key Limits

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/api-keys/<key_id>/limits \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

POST /api/v1/api-keys/{key_id}/regenerate

POST

/api/v1/api-keys/{key_id}/regenerate

Regenerate an API key

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "key_prefix": "example",
  "key": "example",
  "scopes": [],
  "created_at": "example"
}

GET /api/v1/api-keys/{key_id}/usage

GET

/api/v1/api-keys/{key_id}/usage

Get Key Usage

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

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

Response Example

JSON

{
  "api_key_id": "example",
  "api_key_name": "example",
  "total_requests": 0,
  "successful_requests": 0,
  "failed_requests": 0,
  "total_spend_microcents": 0
}

GET /api/v1/api-keys/{key_id}/usage/by-tier

GET

/api/v1/api-keys/{key_id}/usage/by-tier

Get Key Usage By Tier

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/by-tier \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "tiers": []
}

GET /api/v1/api-keys/{key_id}/usage/errors

GET

/api/v1/api-keys/{key_id}/usage/errors

Get Key Usage Errors

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/errors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "total_errors": 0,
  "errors": []
}

GET /api/v1/api-keys/{key_id}/usage/requests

GET

/api/v1/api-keys/{key_id}/usage/requests

Get Key Usage Requests

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
page	`integer`	Optional	Page number (1-based)Default: `1`
page_size	`integer`	Optional	Rows per pageDefault: `50`
status	`"success" \| "failed"`	Optional	Filter by request outcome
tier	`string`	Optional	Filter by tier_used value
domain	`string`	Optional	Substring match on extracted domain
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/requests \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "total": 0,
  "page": 0,
  "page_size": 0,
  "total_pages": 0,
  "items": []
}

GET /api/v1/api-keys/{key_id}/usage/timeseries

GET

/api/v1/api-keys/{key_id}/usage/timeseries

Get Key Usage Timeseries

Parameters

Name	Type	Required	Description
key_id	`string`	Required	API key UUID
days	`integer`	Optional	Days of usage to queryDefault: `30`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/api-keys/<key_id>/usage/timeseries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "api_key_id": "example",
  "days": 0,
  "granularity": "example",
  "data": []
}

Last updated: March 2026