`get_public_vouchers_by_code_availability`

Read-only

Calls GET /api/public/vouchers/{code}/availability as the signed-in person · REST reference

Public voucher availability by code (the voucher QR's landing page)

PUBLIC — no authentication. The code printed on the voucher (its QR encodes https://www.pawsitivefuture.org/voucher?code=<code>) is the only input, and the answer is availability ONLY — never the value, organization, beneficiary, batch or state. How the lifecycle reads: ISSUED with expiresAt in the future is AVAILABLE, and past it EXPIRED; VERIFIED (locked to the clinic that scanned it), PERFORMED_PENDING_CLAIM, CLAIMED, APPROVED, QUEUED_FOR_CHECKOUT, PAID and legacy REDEEMED are USED; VOIDED, VOIDED_REPRINTED (a reprint replaced it — which is not disclosed) and legacy REVOKED are VOID; EXPIRED is EXPIRED; unissued stock (CREATED, ASSIGNED), legacy ACTIVE and AVAILABLE, a soft-deleted voucher, an unknown code and a code that is neither a phrase nor a UUID are all NOT_RECOGNISED. A malformed code is a 200 NOT_RECOGNISED, never a 4xx/5xx — and so is a phrase with a mistyped word: this route never says which word of a code is wrong, because that would confirm the rest of it. Served Cache-Control: no-store. Not throttled here — rate limiting for /api/public/* belongs at the edge.

Arguments

Argument	Type		Description
`code`path	string	required	The voucher code: a phrase of four words, two digits and two symbols (`otter-lantern42kettle_pebble`), matched without regard to case, spaces or dash style, or a legacy UUID. The symbols are `-`, `_`, `+`, `=` and `!`; percent-encode the code in the path. Anything else is answered NOT_RECOGNISED.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_public_vouchers_by_code_availability",
    "arguments": {
      "code": "string"
    }
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The voucher's availability. expiresAt is present only when available is true.

json

{
  "available": true,
  "reason": "AVAILABLE",
  "expiresAt": "2026-01-15T12:00:00Z"
}

Fields

Field	Type	Description
`available`	boolean	True only for reason AVAILABLE.
`expiresAt`	string (date-time)	ISO-8601 instant the voucher stops being accepted. Only when available.
`reason`	"AVAILABLE" \| "EXPIRED" \| "USED" \| "VOID" \| "NOT_RECOGNISED"

When it fails

A failed call returns isError: true with the API's message as text.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_public_vouchers_by_code_availability",
  "description": "GET /api/public/vouchers/{code}/availability — PUBLIC — no authentication. The code printed on the voucher (its QR encodes `https://www.pawsitivefuture.org/voucher?code=<code>`) is the only input, and the answer is availability ONLY — never the value, organization, beneficiary, batch or state. How the lifecycle reads: ISSUED with `expiresAt` in the future is AVAILABLE, and past it EXPIRED; VERIFIED (locked to the clinic that scanned it), PERFORMED_PENDING_CLAIM, CLAIMED, APPROVED, QUEUED_FOR_CHECKOUT, PAID and legacy REDEEMED are USED; VOIDED, VOIDED_REPRINTED (a reprint replaced it — which is not disclosed) and legacy REVOKED are VOID; EXPIRED is EXPIRED; unissued stock (CREATED, ASSIGNED), legacy ACTIVE and AVAILABLE, a soft-deleted voucher, an unknown code and a code that is neither a phrase nor a UUID are all NOT_RECOGNISED. A malformed code is a 200 NOT_RECOGNISED, never a 4xx/5xx — and so is a phrase with a mistyped word: this route never says which word of a code is wrong, because that would confirm the rest of it. Served `Cache-Control: no-store`. Not throttled here — rate limiting for `/api/public/*` belongs at the edge.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "The voucher code: a phrase of four words, two digits and two symbols (`otter-lantern42kettle_pebble`), matched without regard to case, spaces or dash style, or a legacy UUID. The symbols are `-`, `_`, `+`, `=` and `!`; percent-encode the code in the path. Anything else is answered NOT_RECOGNISED."
      }
    },
    "required": [
      "code"
    ]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}