Keys & Billing API

Create API Key

POST /v1/keys

Request Body

{
  "name": "Production Key",
  "expiresInDays": 90
}

Field	Type	Default	Description
name	string	"Default"	Key name (1-100 chars)
expiresInDays	number	-	Days until expiry (1-365). No expiry if omitted.

Response 201

{
  "id": "key_abc123",
  "key": "plabs_sk_live_abc123...",
  "name": "Production Key",
  "expiresAt": "2026-06-21T00:00:00Z",
  "message": "Save this key - it will not be shown again."
}

DANGER

The raw API key is only returned once. Store it immediately in a secure location.

List Keys

GET /v1/keys?limit=20&cursor=key_xyz

Response 200

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "prefix": "plabs_sk_live_abc1...",
      "createdAt": "2026-03-21T00:00:00Z",
      "expiresAt": "2026-06-21T00:00:00Z",
      "lastUsedAt": "2026-03-21T12:00:00Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

The raw key value is never returned in list responses. Only the prefix is shown.

Revoke Key

DELETE /v1/keys/:id

Response 204

No content. The key is immediately invalidated.

Rotate Key

POST /v1/keys/:id/rotate

Creates a new key and revokes the old one atomically.

Response 200

{
  "id": "key_new123",
  "key": "plabs_sk_live_new123...",
  "name": "Production Key",
  "message": "Save this key - it will not be shown again."
}

---

Get Usage

GET /v1/usage

Response 200

{
  "credits": {
    "used": 12500,
    "limit": 200000,
    "remaining": 187500
  },
  "breakdown": {
    "tts": 8000,
    "stt": 2000,
    "llm": 2000,
    "rag": 500
  },
  "requestCount": 3420
}

---

Get Subscription

GET /v1/billing/subscription

Response 200

{
  "tier": "pro",
  "tierDisplay": "Pro ($99/mo)",
  "credits": {
    "used": 12500,
    "limit": 200000,
    "remaining": 187500
  },
  "plan": {
    "monthlyCredits": 200000,
    "overageRate": 0.0008,
    "carryoverMonths": 1
  },
  "stripeCustomerId": "cus_abc123",
  "tierExpiresAt": "2026-04-21T00:00:00Z"
}

Create Checkout Session

Redirect the user to Stripe Checkout to subscribe or upgrade.

POST /v1/billing/checkout

Request Body

{
  "tier": "pro",
  "successUrl": "https://yourapp.com/billing/success",
  "cancelUrl": "https://yourapp.com/billing/cancel"
}

Field	Type	Required	Description
tier	string	yes	starter, pro, or scale
successUrl	string	yes	Redirect URL on successful payment
cancelUrl	string	yes	Redirect URL on cancellation

Response 200

{
  "url": "https://checkout.stripe.com/c/pay/...",
  "sessionId": "cs_live_abc123"
}

Billing Portal

Open the Stripe billing portal for subscription management, invoices, and payment methods.

POST /v1/billing/portal

Response 200

{
  "url": "https://billing.stripe.com/p/session/..."
}