ReqKey.docs
API reference

Plans

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

POST/plan/createBearer

Create plan

Plans are optional, project-level credit templates. Assign a plan to a consumer and its credits are inherited at creation 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 }.

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
  },
  "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"
}
Errors
400Missing planName or credits, 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
  },
  "status": "active",
  "projectKey": "reqkey_xxx...",
  "createdAt": "2026-01-30T12:34:56Z",
  "updatedAt": "2026-01-30T12:34:56Z"
}
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
      },
      "status": "active",
      "createdAt": "2026-01-30T12:34:56Z"
    },
    {
      "planId": "plan_E5F6G7H8",
      "planName": "Starter",
      "credits": {
        "limit": 1000
      },
      "pricing": {
        "monthly": 9.99
      },
      "status": "active",
      "createdAt": "2026-01-29T10:00:00Z"
    }
  ]
}
Errors
401Missing or invalid authentication
POST/plan/updateBearer

Update plan

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

Body
planIdstringrequired

Plan ID to update.

planNamestring

New plan name.

creditsobject

New credit configuration.

pricingobject

New pricing configuration.

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
  }
}'
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 on existing consumers — only new consumers inherit the change.
Errors
400Missing planId
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