Bring your own keys. Share a free one with the pool if you want. [ GET YOUR VAULT ]

Vault Billing & Packages API

A vault key carries three independent facts: how the credential arrived, how it bills, and which package it is on. This page is the API surface for the second and third of those — the fields you set to mark a key a flat-monthly subscription, and the catalogue you pick its package from.

For the dashboard walkthrough see Subscription keys & package tiers. For the vault itself see The Key Vault.

The three axes

Axis

Field

Values

How it arrived

auth_type

api_key · oauth · oauth_pkce · session_token

How it bills

billing_mode

auto · subscription · paid

Which package

subscription_tier

a tier_key from the catalogue, or null

billing_mode is your override. Left at auto, the key's cost_type is derived from its provider (free, paid, subscription or unknown). Set to subscription or paid, your value wins.

The axes are independent, which is the point: an auth_type of api_key and a billing_mode of subscription is a valid, common combination — a MiniMax or Z.ai coding-plan key is pasted like an API key and bills like a subscription.

Base URL

https://spideriq.ai/api/v1

All paths below are relative to that base.

Authentication

Authorization: Bearer <client_id>:<api_key>:<api_secret>
Authorization: Bearer spideriq_pat_…

Reads require a member of the brand named in the path. Writes additionally require a brand admin (session) or a PAT carrying the opt-in gate:vault:write scope. A token that does not own {brand_id} gets 403; a key that belongs to another brand reads as 404, not 403. See Authentication.

Endpoint summary

  • GET /brands/{brand_id}/gate/subscription-tiers — the package catalogue

  • POST /brands/{brand_id}/integrations — add a key, with its billing axis set

  • PATCH /brands/{brand_id}/integrations/{integration_id} — change the billing axis of an existing key

  • GET /brands/{brand_id}/integrations/{integration_id} — read the key back, including its meter

GET /brands/{brand_id}/gate/subscription-tiers

List the curated package catalogue. This is where tier_key values come from — there is no free-text tier.

  • provider — type string · optional · Filter to one provider's packages, e.g. minimax.

curl -s "https://spideriq.ai/api/v1/brands/14/gate/subscription-tiers?provider=minimax" \
  -H "Authorization: Bearer $SPIDERGATE_TOKEN"
{
  "tiers": [
    {
      "provider_name": "minimax",
      "tier_key": "minimax_starter",
      "label": "MiniMax Coding — Starter · $10/mo",
      "price_usd_month": 10.0,
      "window_hours": 5,
      "window_limit": 500,
      "weekly_cap": 10000,
      "sort_order": 10
    },
    {
      "provider_name": "minimax",
      "tier_key": "minimax_plus",
      "label": "MiniMax Coding — Plus · $30/mo",
      "price_usd_month": 30.0,
      "window_hours": 5,
      "window_limit": 1000,
      "weekly_cap": 20000,
      "sort_order": 20
    },
    {
      "provider_name": "minimax",
      "tier_key": "minimax_max",
      "label": "MiniMax Coding — Max · $50/mo",
      "price_usd_month": 50.0,
      "window_hours": 5,
      "window_limit": 2000,
      "weekly_cap": 40000,
      "sort_order": 30
    }
  ]
}

window_hours and window_limit are the two halves of the meter: the length of the rolling window, and how many requests the plan allows inside it. weekly_cap is present only where the plan has a weekly ceiling; it is null otherwise. price_usd_month is null for a plan with no published price.

The catalogue is small and curated on purpose — 14 packages across 6 providers (anthropic, codex, gemini_cli, minimax, zhipu, qwen) as of 10 August 2026. Read it rather than hard-coding a tier_key; plans get renamed and retired.

Note: this route is fail-soft. If the catalogue cannot be read it returns 200 with {"tiers": []} rather than an error, so the key editor still opens. An empty list means "no catalogue available", not "this provider sells no plans".

Setting the billing axis on a key

Both the create and the update path take the same two fields.

  • billing_mode — type string · auto · subscription · paid

  • subscription_tier — type string · a tier_key from the catalogue

curl -s -X PATCH "https://spideriq.ai/api/v1/brands/14/integrations/42" \
  -H "Authorization: Bearer $SPIDERGATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"billing_mode": "subscription", "subscription_tier": "minimax_max"}'

Setting subscription_tier copies that package's window_hours and window_limit onto the key as sub_window_hours and sub_window_limit. That is what gives the capacity meter a denominator. Change the package later and the window is re-seeded from the new one.

subscription_tier is a soft reference, not a foreign key. A tier_key the catalogue does not contain is accepted and stored, and the window is left unset — the request succeeds, the meter stays blank, and a warning is logged. Read the catalogue first and this cannot happen.

Which subscription keys can be pooled

A key whose billing_mode is paid cannot be shared into the pool, and neither can a subscription key — with one exception: a ChatGPT (Codex) subscription (provider_name: codex) can be shared with the pool. Every other subscription key stays private to your brand. Sending share_with_pool: true with a refused billing_mode in one request is rejected:

{"error": {"code": "HTTP_ERROR_422", "message": "A key marked billing_mode='subscription' is private to your brand and cannot be shared with the pool."}}

This body is the app's own error wrapper run on that message. Every error from this API is wrapped as {"error": {"code", "message", …}}; there is no top-level detail.

422 Unprocessable Entity. The rule is also enforced in the database, so a key cannot end up pooled by any other path either. The API returns the error rather than silently un-ticking the box you just ticked.

cost_type: free keys are unaffected and still pool normally.

A codex key marked subscription keeps the share setting it is saved with. Sharing a codex subscription key that was saved unshared also makes it pool-eligible again, so the pool can use it.

Subscription logins are always billed as Subscription

codex, anthropic, cursor, grok and gemini_cli sign in with a subscription login, so their keys are always billing_mode: subscription:

  • On create, leaving billing_mode out stores subscription.

  • Sending paid is a 422, and so is auto for anthropic, cursor and grok, whose provider class is paid. The message is "<provider> signs in with a subscription login, so its key is billed as Subscription. billing_mode='paid' would mark it pay-per-use. Send billing_mode='subscription', or leave it out."

  • On update, only a billing_mode sent in that request is checked; a stored value is left as it is.

Providers that sell both a pay-as-you-go key and a coding plan (MiniMax, Z.ai, Qwen, DeepSeek) keep all three values.

Reading the meter

GET /brands/{brand_id}/integrations/{integration_id} returns the billing axis and the meter together:

Field

Meaning

cost_type

free · subscription · paid · unknown — the effective class after any billing_mode override

billing_mode

the override itself, auto unless you set one

subscription_tier

the package key, or null

chatgpt_plan

codex only: the ChatGPT plan OpenAI states for this login (plus, pro, prolite, team, …), or null when OpenAI has not said yet. Read from the plan usage reply, else from the sign-in token

chatgpt_plan_warning

codex only: a sentence when that plan clearly does not match subscription_tier (for example a team login on a Pro package), else null. A Pro package on a pro or prolite login is never flagged, because neither reply says which Pro package it is

sub_window_hours

window length copied from the package

sub_window_limit

request allowance copied from the package — the denominator. null when the package publishes no request limit

sub_window_count

tokens counted inside the current window. Spend, not the numerator

sub_window_request_count

requests counted inside the current window — the numerator

sub_window_reset_at

when the window rolls. null on a key with no window length

sub_window_percent

sub_window_request_count / sub_window_limit * 100, or null

sub_window_percent is null in three cases: no package is set, the package publishes no request limit, or the request count is so far past the limit that the two cannot be the same unit. A null meter never means "no usage". A window that has a limit and no requests yet reads 0.

CLI

# discover the packages
spideriq gate subscription-tiers --brand 14 --provider minimax

# set the billing axis and the package together
spideriq gate keys update 42 \
  --billing-mode subscription \
  --subscription-tier minimax_max

MCP

  • get_subscription_tiers — the catalogue

  • create_brand_integration — add a key with billing_mode + subscription_tier

  • update_brand_integration — change them on an existing key

  • gate_key_update — the same change from the admin surface

Errors

Status

When

400

brand_id is not an integer

403

the token does not own {brand_id}

404

the key exists but belongs to another brand

422

share_with_pool: true combined with billing_mode subscription or paid

See Errors for the full response shape.