API keys

List API keys

GET/api/v1/api-keys

GET /api-keys
curl -X GET 'https://www.unitpost.com/api/v1/api-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "api_key",
      "id": "id_123",
      "name": "Example",
      "prefix": "string",
      "scope": "full",
      "capabilities": [
        "string"
      ],
      "last_used_at": "2026-01-01T00:00:00.000Z",
      "revoked_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your workspace's API keys — the key prefix, scope, capabilities and last use, never the secret. With an API key or an MCP sign-in it needs apikeys:read, which no key preset includes: tick it on the key that audits your keys. From a dashboard session it needs apikeys:manage. See how a key is used with Retrieve an API key's usage. Creating (Create an API key) and revoking (Revoke an API key) keys stay in a dashboard session. Requires the apikeys:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
prefixrequiredstring—
scoperequiredenumfull | sending | read_only—
capabilitiesrequiredstring[]—
last_used_atrequiredstring | null—
revoked_atrequiredstring | null—
created_atrequiredstring—
200401403422

Create an API key

POST/api/v1/api-keys

POST /api-keys
curl -X POST 'https://www.unitpost.com/api/v1/api-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production server",
    "capabilities": [
      "emails:send"
    ]
  }'
Response · 201
{
  "object": "api_key",
  "id": "id_123",
  "name": "Example",
  "prefix": "string",
  "scope": "full",
  "capabilities": [
    "string"
  ],
  "last_used_at": "2026-01-01T00:00:00.000Z",
  "revoked_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "key": "string"
}

Create an API key scoped to the capabilities you choose. The response includes the plaintext key exactly once — store it securely now, because it can never be retrieved again (only revoked). This endpoint is session-gated: it requires a dashboard session and cannot be called with a Bearer API key.

Request body3 fields
FieldTypeDescription
namerequiredstring—
scopeenumfull | sending | read_only—
capabilitiesenum[]—
Response · 201 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
prefixrequiredstring—
scoperequiredenumfull | sending | read_only—
capabilitiesrequiredstring[]—
last_used_atrequiredstring | null—
revoked_atrequiredstring | null—
created_atrequiredstring—
keyrequiredstringThe plaintext secret. Shown exactly once — store it now; it can never be retrieved again.
201401403422

List request logs

GET/api/v1/logs

GET /logs
curl -X GET 'https://www.unitpost.com/api/v1/logs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "request_log",
      "id": "id_123",
      "request_id": "request_123",
      "method": "string",
      "path": "string",
      "status": 0,
      "duration_ms": 0,
      "api_key_id": "api_key_123",
      "user_agent": "string",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your workspace's API request log, newest first and cursor-paginated: each call's method, path, status, time taken, the API key that made it and its x-request-id (quote it to support). Never the caller's IP and never a body. Narrow with status (a code, or a class such as 4xx), api_key_id, method, path_prefix (e.g. /email), request_id and a created_after / created_before range. Rows are kept 30 days. Needs apikeys:read, which no key preset includes, and has its own per-workspace rate limit. Requires the apikeys:read capability.

Parameters10 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryA status code (e.g. `429`) or a class: `2xx`, `3xx`, `4xx`, `5xx`.
api_key_idstring · queryOnly one API key's calls (`key_…`).
methodstring · queryOnly one HTTP method.
path_prefixstring · queryOnly paths under this one, as in this reference (e.g. `/email/campaigns`): whole path segments, matched literally (`/email` matches `/email` and `/email/campaigns`, not `/emails`). It can't name an email address or a phone number (paths show them as `{email}` / `{phone}`).
request_idstring · queryOne call, by the `x-request-id` its response carried. Searches the last 24 hours unless `created_after` is given.
created_afterstring · queryCalls at or after this time (ISO 8601 with a zone).
created_beforestring · queryCalls before this time (ISO 8601 with a zone).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe log row (`rlog_…`); page with it as `after` / `before`.
request_idrequiredstring | nullThe `x-request-id` the response carried: quote it to support.
methodrequiredstring—
pathrequiredstringThe path called, without the host and `/api/v1` (e.g. `/email/email_…`); no query string. An email address or phone number in it reads `{email}` / `{phone}`.
statusrequiredintegerThe HTTP status answered.
duration_msrequiredinteger | nullHow long the request took to answer.
api_key_idrequiredstring | nullThe API key that called (`key_…`); null for an MCP or CLI sign-in, or a key since deleted.
user_agentrequiredstring | null—
created_atrequiredstring—
200401403422429503

Retrieve an API key's usage

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

GET /api-keys/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/api-keys/key_123/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "api_key_usage",
  "id": "id_123",
  "last_used_at": "2026-01-01T00:00:00.000Z",
  "requests_24h": 0,
  "client_errors_24h": 0,
  "server_errors_24h": 0,
  "rate_limited_24h": 1
}

One key's last 24 hours: how many requests it made, how many were answered 4xx, 5xx or 429, and when it was last used. Check it before you revoke a key (is anything still calling with it?) or when an integration's calls fail. The dashboard's revoke dialog reads the same count. Needs apikeys:read, which no key preset includes. Requires the apikeys:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe key (`key_…`).
last_used_atrequiredstring | null—
requests_24hrequiredintegerRequests the key made in the last 24 hours, counted up to 100,000: `100001` means more than 100,000.
client_errors_24hrequiredintegerOf those, answered 4xx (`rate_limited_24h` included). Past the cap, these three count the latest 100,001 requests.
server_errors_24hrequiredintegerOf those, answered 5xx.
rate_limited_24hrequiredintegerOf those, answered 429.
200401403404422503

Revoke an API key

DELETE/api/v1/api-keys/{id}

DELETE /api-keys/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/api-keys/key_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently revoke an API key. Requests made with it start failing with 401 immediately, and revocation cannot be undone — create a replacement first with Create an API key if you're rotating. This endpoint is session-gated: it requires a dashboard session and cannot be called with a Bearer API key.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404

Search docs and guides

Search the docs and product guides.