Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

API Keys

List, create and revoke the secret keys on a project, so an agent can rotate its own credentials. All key endpoints need a secret key (pv_live_ / pv_test_); publishable keys get 403.

The API key object

The new API key.

Properties

The API key object properties
Property Type Description
id string

Key id, used by revoke_key.

api_key string

The raw key. Shown only in this response.

type string

Always secret.

One of: secret

environment string

One of: live, test

label string nullable
created_at string (date-time)
The API key object
{
  "id": "key_abc123",
  "api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "secret",
  "environment": "live",
  "label": "ci",
  "created_at": "2026-11-16T12:00:00.000Z"
}

List API keys

GET /v1/keys

Every key on the calling key's project, oldest first, secret and publishable. Hashes and raw keys are never returned; current marks the key that made this request. Requires a secret key.

Authentication

API key, sent as Authorization: Bearer <key>.

Responses

  • 200

    Keys

  • 401

    missing_api_key: no Authorization header. invalid_api_key: the header is not Bearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked.

  • 403

    publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl https://api.pixelvault.dev/v1/keys \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": [
    {
      "id": "key_abc123",
      "type": "secret",
      "environment": "live",
      "label": "ci",
      "key_prefix": "pv_live_",
      "allowed_origins": null,
      "created_at": "2026-11-16T12:00:00.000Z",
      "last_used_at": "2026-11-16T12:30:00.000Z",
      "current": true
    }
  ]
}

Create an API key

POST /v1/keys

Mint an additional secret key for the project, so an agent can rotate its own credentials. The raw key is returned once and cannot be retrieved again; keys are hashed server-side. A project can hold at most 25 keys (exact, enforced atomically), and creating or revoking keys is limited to 20 changes per hour per project.

To rotate: create a new key, switch to it, then revoke the old one with revoke_key using the new key. Publishable keys are managed in the dashboard. Requires a secret key; an empty body is fine.

Authentication

API key, sent as Authorization: Bearer <key>.

Request body

application/json, optional

Request body
Name Type Required Description
label string Optional

Optional name, trimmed; blank means none.

max length 60

environment string Optional

live mints a pv_live_ key, test a pv_test_ key.

One of: live, test

Default: live

Responses

  • 201

    Key created. Store api_key now.

  • 400

    validation_error: the body is not a JSON object, label is not a string or is longer than 60 characters, or environment is not live or test.

  • 401

    missing_api_key: no Authorization header. invalid_api_key: the header is not Bearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked.

  • 403

    publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 409

    key_limit_reached: the project already holds 25 keys; revoke one first.

  • 429

    rate_limit_exceeded: more than 20 key creations and revocations per hour for the project, or the per-key request limit. Honour Retry-After.

Request
curl -X POST https://api.pixelvault.dev/v1/keys \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"ci","environment":"live"}'
Response 201
{
  "data": {
    "id": "key_abc123",
    "api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "secret",
    "environment": "live",
    "label": "ci",
    "created_at": "2026-11-16T12:00:00.000Z"
  }
}

Revoke an API key

DELETE /v1/keys/{id}

Permanently revoke a secret key on the project. Only secret keys can be revoked here (publishable keys are managed from the dashboard and return 404). A key cannot revoke itself (cannot_revoke_current_key), so to rotate: create a new key, switch to it, then revoke the old one with the new key.

A revoke only applies while the key making the request still exists, so two keys revoking each other at the same moment cannot leave the project without a key; the loser gets 409 conflict. Limited to 20 key changes per hour per project. Requires a secret key.

Authentication

API key, sent as Authorization: Bearer <key>.

Path parameters

Path parameters
Name Type Required Description
id string Required

Key id from list_keys.

Responses

  • 200

    Revoked

  • 401

    missing_api_key: no Authorization header. invalid_api_key: the header is not Bearer pv_live_…/pv_test_…/pv_pub_…, or the key is unknown or revoked.

  • 403

    publishable_key_forbidden: publishable keys (pv_pub_) can only upload images; use a secret key. account_suspended: the account is suspended.

  • 404

    not_found: no secret key with this id on the project.

  • 409

    cannot_revoke_current_key: the request is authenticated with that key. conflict: already revoked, or the calling key was revoked at the same moment; list the keys and retry.

  • 429

    rate_limit_exceeded: more than 20 key creations and revocations per hour for the project, or the per-key request limit. Honour Retry-After.

Request
curl -X DELETE https://api.pixelvault.dev/v1/keys/key_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": {
    "deleted": true
  }
}