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

Auto-refill: { interval: "hour"|"day"|"week"|"month", amount }.

overageobject

Overage: { enabled, limit }.

expiresAtnumber

Credit expiration timestamp (ms).

pricingobject

Pricing, e.g. { "monthly": 99.99, "annual": 999 }.

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. Default "active".

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": {
      "interval": "month",
      "amount": 50000
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "monthly": 299.99,
    "annual": 2999.99
  },
  "rateLimit": {
    "limit": 100,
    "window": 60
  },
  "status": "active"
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "planName": "Enterprise",
  "credits": {
    "limit": 100000,
    "shadowLimit": 10000,
    "refill": {
      "interval": "month",
      "amount": 50000
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "monthly": 299.99,
    "annual": 2999.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 or credits, 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": {
      "interval": "month",
      "amount": 50000
    },
    "overage": {
      "enabled": true,
      "limit": 5000
    }
  },
  "pricing": {
    "monthly": 299.99,
    "annual": 2999.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": {
        "monthly": 299.99
      },
      "rateLimit": {
        "limit": 100,
        "window": 60
      },
      "status": "active",
      "createdAt": "2026-01-30T12:34:56Z"
    },
    {
      "planId": "plan_E5F6G7H8",
      "planName": "Starter",
      "credits": {
        "limit": 1000
      },
      "pricing": {
        "monthly": 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": {
    "monthly": 349.99,
    "annual": 3499.99
  },
  "rateLimit": {
    "limit": 50,
    "window": 60
  }
}'
Response
{
  "planId": "plan_A1B2C3D4",
  "planName": "Enterprise",
  "credits": {
    "limit": 150000
  },
  "pricing": {
    "monthly": 349.99,
    "annual": 3499.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