Public reference

Cards

Every endpoint in this group. Open one for its parameters and a worked example.

10 Endpoints

Cards

POST /api/v1/admin/cards/redeem-otc Redeem a card over the counter prm_cards_verify

The same operation as the subscriber-facing redeem, with one difference: the acting manager is recorded as the reseller, so the redemption snapshots what they paid against what they charged. Without that, per-reseller pricing never resolves and every redemption records face value on both sides.

Authentication: Staff token or session
Requires permission: prm_cards_verify Verify / redeem cards
Rate limit: card_redeem
Idempotency key: request_id

Parameters

Parameter	Description
`code`required body · string	The plaintext card code.
`user_id`required body · integer	The subscriber to credit.
`request_id`required body · string	Idempotency key.

Open the full reference

POST /api/v1/admin/cards/redeem-to-wallet Top up own wallet online prm_managers_self_deposit

Authentication: Staff token or session
Requires permission: prm_managers_self_deposit Top up own wallet online
Rate limit: card_wallet_redeem

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/admin/cards/redemptions/{id} View card batches & cards prm_cards_list

Authentication: Staff token or session
Requires permission: prm_cards_list View card batches & cards

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/admin/cards/redemptions/{id}/reversals View card batches & cards prm_cards_list

Authentication: Staff token or session
Requires permission: prm_cards_list View card batches & cards

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/admin/cards/redemptions/{id}/reversals Refund last activation prm_users_refund

Authentication: Staff token or session
Requires permission: prm_users_refund Refund last activation
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/cards/redeem Redeem a card onto a subscriber prm_cards_verify

Spends a card and applies its effect to the named subscriber. Two authority checks run, both derived from your credential and neither from the body: the card must be in your subtree, and the subscriber must be one you may write to. Both denials are 404s identical to "no such card" and "no such subscriber".

Authentication: Staff token or session
Requires permission: prm_cards_verify Verify / redeem cards
Rate limit: card_redeem
Idempotency key: request_id

A replay returns 200 with the same card_id, mode and effect_applied, and NO replay flag — but new_balance is ABSENT, because the replay path returns the stored effect without re-reading the wallet. A missing new_balance is not a failure and is not a reason to retry. Read the balance off the subscriber record if you need it.

Parameters

Parameter	Description
`code`required body · string	The plaintext card code.
`user_id`required body · integer	The subscriber to credit.
`request_id`required body · string	Idempotency key.

Open the full reference

Response 200 OK

{
  "data": {
    "card_id": 90211,
    "mode": "refill_balance",
    "user_id": 4711,
    "effect_applied": { "type": "add_balance", "amount": 150.00 },
    "new_balance": 400.00
  }
}

POST /api/v1/cards/redeem-create

Authentication: Public
Rate limit: card_redeem

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/cards/search Verify one card by code, serial or username prm_cards_verify

The counter-staff lookup. Finds a single card and reports its state, its owning reseller and who spent it. Confined to the caller's manager subtree unless they are an administrator.

Authentication: Staff token or session
Requires permission: prm_cards_verify Verify / redeem cards
Rate limit: card_search

A card outside your subtree answers the same 404 as an unknown keyword, never a 403 — a 403 would confirm the code exists and turn this into a code-guessing oracle. It carries its own per-operator budget for the same reason, separate from the tenant's.

Parameters

Parameter	Description
`kind`required query · enum	code, serial or username.
`keyword`required query · string	The value to match. A code is normalised first, so separators and mixed case still resolve.

Open the full reference

Response 200 OK

{
  "data": {
    "card_id": 90211,
    "serial": "000312",
    "state": "consumed",
    "effective_state": "consumed",
    "disposition": "",
    "mode": "voucher_account",
    "plan_name": "Home 20M",
    "batch_id": 208,
    "face_value": 150.00,
    "redemptions_left": 0,
    "owner_manager_id": 41,
    "owner_username": "cairo-reseller",
    "used_by_kind": "user",
    "used_by_user_id": 4711,
    "used_by_username": "ahmed",
    "used_channel": "customer_portal",
    "first_use_at": "2026-09-14 18:22:10",
    "expires_at": "2027-01-01 00:00:00"
  }
}

POST /api/v1/cards/{id}/revoke Revoke one card prm_cards_suspend_release

Flips a single card to revoked. A revoked card can never be redeemed, and the state is terminal.

Authentication: Staff token or session
Requires permission: prm_cards_suspend_release Suspend / release cards
Rate limit: t_mutate

Parameters

Parameter	Description
`id`required path · integer	Card id.

Open the full reference

GET /api/v1/cards/{id}/timeline One card's full lifecycle prm_cards_list

Header facts plus the chronological event list for a single card: when it was minted, printed, sold, transferred and redeemed.

Authentication: Staff token or session
Requires permission: prm_cards_list View card batches & cards
Rate limit: card_timeline

This endpoint's rate-limit bucket counts DENIED lookups too, on purpose. The limiter sits ahead of the visibility check, so a walk of the card id space burns budget rather than running unmetered behind a 404.

Parameters

Parameter	Description
`id`required path · integer	Card id.

Open the full reference

Written to be read by machines too

The reference is public and needs no account, so a tool that has never seen X-Radius can reach a correct first call on its own.

/llms.txt: An index of every page, with one-line summaries.
/llms-full.txt: The whole reference as one Markdown file, with no navigation to crawl.
/openapi.json: OpenAPI 3.1, generated from the router that serves this instance.
/skill.md: A ready-made skill file for an assistant: authentication, the response envelope and the error codes in one page.
<page-url>.md: Append .md to any reference URL for the same page as Markdown.
Accept: text/markdown: Send this header on the ordinary URL and the answer comes back as Markdown instead.

Hand this to your assistant

Read https://x-radius.com/llms.txt, then fetch the endpoint you need as Markdown by appending .md to its URL.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us