ReqKeydocs
API reference

Plans

Optional templates that bundle a credit limit, refill, overage, pricing, and a rate limit. Assign one to a consumer to inherit its credits and rate limit.

POST/plan/createBearer

Create plan

Plans are optional, project-level templates. Assign a plan to a consumer and its credits — and rate limit, if the plan sets one — are inherited at attach time.

Body
planNamestringrequired

Name of the plan.

creditsobjectrequired

Credit configuration.

limitnumber

Total credit limit.

shadowLimitnumber

Warning threshold — fires alerts before the hard limit.

refillobject | null

Auto-refill schedule.

everystringrequired

Interval as <number><unit>, unit h (hours) or d (days): "1h", "1d", "7d", "30d". Anything else is silently treated as 1 day — there is no "month" keyword; use "30d".

refillCreditnumberrequired

Credits granted at each refill.

refillPolicystring

"reset" (default) starts a fresh pool each interval; "add" tops up on top of what is left.

carryoverobject

Roll unused credits into the next interval: { enabled, max }.

overageobject

Overage: { enabled, limit }.

expiresAtnumber

Credit expiration timestamp (ms).

pricingobjectrequired

Informational pricing shown in the dashboard — ReqKey never charges anyone. Required; send {} if you have nothing to record. Recognized fields: currency (default "USD"), fixedCharge.

rateLimitobject

Rate limit consumers inherit when they attach to this plan: limit requests per window seconds.

limitnumberrequired

Max /key/validate requests per window. 1 – 1,000,000,000.

windownumber

Window length in seconds, 1 – 86,400. Default 1. E.g. 100/minute is { limit: 100, window: 60 }.

statusstring

Plan status: "draft" (default), "active", or "archived".

Request
curl -X POST "https://api.reqkey.com/plan/create" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "planName": "Enterprise",
  "credits": {
    "limit": 100000,
    "shadowLimit": 10000,
    "refill": {
      "every": "30d",
      "refillCredit": 50000,
      "refillPolicy": "reset"
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "currency": "USD",
    "fixedCharge": 299.99
  },
  "rateLimit": {
    "limit": 100,
    "window": 60
  },
  "status": "active"
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "planName": "Enterprise",
  "credits": {
    "limit": 100000,
    "shadowLimit": 10000,
    "refill": {
      "every": "30d",
      "refillCredit": 50000,
      "refillPolicy": "reset"
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "currency": "USD",
    "fixedCharge": 299.99
  },
  "status": "active",
  "projectKey": "reqkey_xxx...",
  "createdAt": "2026-01-30T12:34:56Z"
}
  • rateLimit is copy-on-attach, exactly like credits: consumers inherit it when they attach to the plan, and changing it later never touches consumers already on the plan.
Errors
400Missing planName, credits, or pricing; invalid rateLimit; or body parse error
401Missing or invalid authentication
500Temporary internal error — safe to retry
POST/plan/detailsBearer

Get plan details

Fetch a single plan.

Body
planIdstringrequired

Plan ID to retrieve.

Request
curl -X POST "https://api.reqkey.com/plan/details" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan_A1B2C3D4"
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "planName": "Enterprise",
  "credits": {
    "limit": 100000,
    "shadowLimit": 10000,
    "refill": {
      "every": "30d",
      "refillCredit": 50000,
      "refillPolicy": "reset"
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "currency": "USD",
    "fixedCharge": 299.99
  },
  "rateLimit": {
    "limit": 100,
    "window": 60
  },
  "status": "active",
  "projectKey": "reqkey_xxx...",
  "createdAt": "2026-01-30T12:34:56Z",
  "updatedAt": "2026-01-30T12:34:56Z"
}
  • rateLimit is null when the plan does not set one.
Errors
400Missing planId
403Plan does not belong to this project
404Plan not found
POST/plan/listBearer

List plans

List all plans in the project.

Request
curl -X POST "https://api.reqkey.com/plan/list" \
  -H "Authorization: Bearer reqkey_xxx..."
Response
{
  "total": 2,
  "plans": [
    {
      "planId": "plan_A1B2C3D4",
      "planName": "Enterprise",
      "credits": {
        "limit": 100000
      },
      "pricing": {
        "currency": "USD",
        "fixedCharge": 299.99
      },
      "rateLimit": {
        "limit": 100,
        "window": 60
      },
      "status": "active",
      "createdAt": "2026-01-30T12:34:56Z"
    },
    {
      "planId": "plan_E5F6G7H8",
      "planName": "Starter",
      "credits": {
        "limit": 1000
      },
      "pricing": {
        "currency": "USD",
        "fixedCharge": 9.99
      },
      "rateLimit": null,
      "status": "active",
      "createdAt": "2026-01-29T10:00:00Z"
    }
  ]
}
Errors
401Missing or invalid authentication
POST/plan/updateBearer

Update plan

Change a plan’s credits, rate limit, pricing, name, or status.

Body
planIdstringrequired

Plan ID to update.

planNamestring

New plan name.

creditsobject

New credit configuration.

pricingobject

New pricing configuration.

rateLimitobject | null

New rate limit, or null to remove the plan’s rate limit.

limitnumberrequired

Max /key/validate requests per window. 1 – 1,000,000,000.

windownumber

Window length in seconds, 1 – 86,400. Default 1.

statusstring

New status.

Request
curl -X POST "https://api.reqkey.com/plan/update" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan_A1B2C3D4",
  "credits": {
    "limit": 150000
  },
  "pricing": {
    "currency": "USD",
    "fixedCharge": 349.99
  },
  "rateLimit": {
    "limit": 50,
    "window": 60
  }
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "planName": "Enterprise",
  "credits": {
    "limit": 150000
  },
  "pricing": {
    "currency": "USD",
    "fixedCharge": 349.99
  },
  "status": "active",
  "updatedAt": "2026-01-30T14:00:00Z"
}
  • Updating a plan does not retroactively change credits or rate limits on existing consumers — only consumers that attach after the change inherit the new values.
  • rateLimit: null removes the rate limit from the plan (future attaches inherit no limit).
Errors
400Missing planId or invalid rateLimit
403Plan does not belong to this project
404Plan not found
POST/plan/deleteBearer

Delete plan

Soft or hard delete a plan.

Body
planIdstringrequired

Plan ID to delete.

permanentboolean

false = soft delete (default), true = hard delete.

Request
curl -X POST "https://api.reqkey.com/plan/delete" \
  -H "Authorization: Bearer reqkey_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "plan_A1B2C3D4",
  "permanent": false
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "deleted": true,
  "permanent": false,
  "deletedAt": "2026-01-30T12:34:56Z",
  "message": "Plan soft deleted."
}
  • Existing consumers referencing this plan are not affected by the delete.
Errors
400Missing planId
403Plan does not belong to this project
404Plan not found
PreviousAPIsNext Consumers