{ "openapi": "3.1.0", "info": { "title": "Evolution Boost Reseller API", "version": "1.0.0", "summary": "REST API for official Evolution Boost resellers: top up a BRL balance with PIX, buy Steam hour-boost license keys with it and look up your keys.", "description": "## Introduction\n\nThe Evolution Boost Reseller API lets official resellers top up a balance with PIX, buy license keys with that balance and look up their keys (free, redeemed or all) from their own systems, bots or stores.\n\nIt is a JSON REST API over HTTPS. The base URL is `https://evolutionboost.xyz/api/v1`. It is meant for server-to-server use: never call it from a browser or ship your API key inside an app (there is no CORS).\n\n## Authentication\n\nAuthenticate every request with your API key in the `Authorization` header as a Bearer token. Keys start with `evb_live_` and are created by the Evolution Boost team in the admin panel. You receive the full key only once, so store it in a secret manager or environment variable.\n\n## Errors\n\nErrors use conventional HTTP status codes and a JSON body. Branch on `error.type` and `error.code`, never on `message`. `param` points to the field or header that caused the error.\n\n## Pagination\n\nList endpoints return `{\"object\": \"list\", \"data\": [...], \"has_more\": bool}`, newest first. Use `limit` (1 to 100, default 20) and, to get the next page, pass the `id` of the last object you received as `starting_after`. Stop when `has_more` is `false`.\n\n## Idempotency\n\nEvery `POST` that moves money or creates keys requires an `Idempotency-Key` header. Generate a new UUID for each operation and reuse it only to retry that same operation (timeouts, network errors, 5xx). A retry never charges twice: it returns the original result.\n\n## Rate limits\n\nLimits are counted per API key (authentication failures, per IP). Going over returns `429 rate_limit_exceeded` with a `Retry-After` header in seconds. Wait that long before retrying.\n\n## Quickstart\n\nThe recommended flow, from an empty balance to keys in hand:", "contact": { "name": "Evolution Boost", "url": "https://discord.evolutionboost.xyz/" } }, "externalDocs": { "description": "Full documentation", "url": "https://evolutionboost.xyz/docs/api" }, "servers": [ { "url": "https://evolutionboost.xyz/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Me", "description": "Who you are: reseller, API key in use and balance. A good first call to test your integration." }, { "name": "Packages", "description": "Plans available to resellers, with your wholesale price." }, { "name": "Balance", "description": "Your prepaid balance in BRL. Deposits credit it; key purchases debit it." }, { "name": "Ledger", "description": "Every balance movement, immutable, with the balance after each one." }, { "name": "Deposits", "description": "PIX charges that credit your balance. From R$ 10,00 to R$ 5.000,00 each, at most 3 pending at a time." }, { "name": "Keys", "description": "Buy license keys with your balance and look up the keys you own." } ], "paths": { "/me": { "get": { "operationId": "meRetrieve", "summary": "Retrieve the reseller", "description": "Returns the reseller that owns the API key, the key used and the current balance.", "tags": [ "Me" ], "parameters": [], "responses": { "200": { "description": "The reseller.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reseller" }, "example": { "object": "reseller", "id": "5f0c2a3e-8d41-4b6a-9e2f-1c7d3b9a6e10", "name": "ACME Games", "code": "ACME", "status": "active", "token": { "name": "Store backend", "prefix": "xxxxxxxx" }, "balance": { "object": "balance", "balance_cents": 125000, "currency": "BRL", "updated_at": "2026-10-17T14:10:03.000Z" } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/packages": { "get": { "operationId": "packagesList", "summary": "List packages", "description": "Lists the packages you can buy keys for, with your wholesale price per key. Packages without a wholesale price are not listed and cannot be bought. Not paginated (`has_more` is always `false`).", "tags": [ "Packages" ], "parameters": [], "responses": { "200": { "description": "The list of packages.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageList" }, "example": { "object": "list", "data": [ { "object": "package", "code": "H150", "hours": 150, "account_limit": 3, "price_cents": 499, "currency": "BRL" }, { "object": "package", "code": "H600", "hours": 600, "account_limit": 6, "price_cents": 1099, "currency": "BRL" }, { "object": "package", "code": "H1200", "hours": 1200, "account_limit": 12, "price_cents": 1899, "currency": "BRL" } ], "has_more": false } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/balance": { "get": { "operationId": "balanceRetrieve", "summary": "Retrieve the balance", "description": "Returns the current balance of your wallet, in cents of BRL.", "tags": [ "Balance" ], "parameters": [], "responses": { "200": { "description": "The balance.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "object": "balance", "balance_cents": 125000, "currency": "BRL", "updated_at": "2026-10-17T14:10:03.000Z" } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/ledger": { "get": { "operationId": "ledgerList", "summary": "List ledger entries", "description": "Lists balance movements, newest first. Paginated.", "tags": [ "Ledger" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return, between 1 and 100. Default 20.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "starting_after", "in": "query", "required": false, "description": "Cursor: the `id` of the last object of the previous page. Returns the objects that come after it.", "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "description": "Only movements of this kind.", "schema": { "type": "string", "enum": [ "deposit", "key_purchase", "adjustment", "refund" ] }, "example": "key_purchase" } ], "responses": { "200": { "description": "A page of ledger entries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEntryList" }, "example": { "object": "list", "data": [ { "object": "ledger_entry", "id": "7d6c5b4a-3f2e-4d1c-9b0a-8f7e6d5c4b3a", "kind": "key_purchase", "amount_cents": -5990, "balance_after_cents": 125000, "currency": "BRL", "ref_type": "key_batch", "ref_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "description": "10x H150, 1x H600", "created_at": "2026-10-17T14:10:03.000Z" }, { "object": "ledger_entry", "id": "2e3f4a5b-6c7d-4e8f-a9b0-c1d2e3f4a5b6", "kind": "deposit", "amount_cents": 50000, "balance_after_cents": 130990, "currency": "BRL", "ref_type": "deposit", "ref_id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b", "description": "Deposito PIX", "created_at": "2026-10-17T14:02:41.000Z" } ], "has_more": true } } } }, "400": { "description": "`invalid_limit`, `invalid_cursor`, `invalid_kind`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_limit": { "summary": "`limit` must be an integer between 1 and 100.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_limit", "message": "limit must be an integer between 1 and 100.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_cursor": { "summary": "`starting_after` is not a UUID or is not an object of this list.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "starting_after is not a UUID or is not an object of this list.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_kind": { "summary": "Unknown value in the `kind` filter.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_kind", "message": "Unknown value in the kind filter.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/deposits": { "post": { "operationId": "depositsCreate", "summary": "Create a deposit", "description": "Creates a PIX charge for `amount_cents`. Pay `br_code` (copy-and-paste) or the QR in `br_code_base64`; the balance is credited automatically once the payment is confirmed. Then poll `GET /deposits/{id}`. At most 3 pending deposits at a time.", "tags": [ "Deposits" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (a UUID is ideal), 1 to 255 visible ASCII characters. Retrying with the same key never charges twice.", "schema": { "type": "string" }, "example": "6c1f7d0e-4b9a-4a39-9d4e-2b8f0c7a1e55" } ], "responses": { "200": { "description": "The pending deposit with the PIX code. A retry with the same `Idempotency-Key` returns the same deposit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "example": { "object": "deposit", "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b", "amount_cents": 50000, "currency": "BRL", "status": "pending", "br_code": "00020101021226850014br.gov.bcb.pix...6304A1B2", "br_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "expires_at": "2026-10-18T14:00:00.000Z", "created_at": "2026-10-17T14:00:00.000Z", "paid_at": null } } } }, "400": { "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_json`, `invalid_amount`, `too_many_pending_deposits`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "POST without the `Idempotency-Key` header.", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_key_required", "message": "POST without the Idempotency-Key header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_idempotency_key": { "summary": "`Idempotency-Key` must have 1 to 255 visible ASCII characters, no spaces.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_idempotency_key", "message": "Idempotency-Key must have 1 to 255 visible ASCII characters, no spaces.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_json": { "summary": "The body is empty, is not JSON or is not a JSON object.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "The body is empty, is not JSON or is not a JSON object.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_amount": { "summary": "`amount_cents` must be an integer between 1000 and 500000.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_amount", "message": "amount_cents must be an integer between 1000 and 500000.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "too_many_pending_deposits": { "summary": "You already have 3 pending deposits. Pay one or wait for it to expire.", "value": { "error": { "type": "invalid_request_error", "code": "too_many_pending_deposits", "message": "You already have 3 pending deposits. Pay one or wait for it to expire.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "409": { "description": "`idempotency_key_reused`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_reused": { "summary": "The `Idempotency-Key` was already used with a different body. Use a new key for a new operation.", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different body. Use a new key for a new operation.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "413": { "description": "`payload_too_large`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "summary": "The body is larger than 24000 bytes.", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The body is larger than 24000 bytes.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "502": { "description": "`payment_provider_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payment_provider_error": { "summary": "The PIX provider failed to create the charge. Retry later.", "value": { "error": { "type": "api_error", "code": "payment_provider_error", "message": "The PIX provider failed to create the charge. Retry later.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1000, "maximum": 500000, "description": "Amount in cents of BRL, from 1000 (R$ 10,00) to 500000 (R$ 5.000,00).", "examples": [ 50000 ] } }, "required": [ "amount_cents" ] }, "example": { "amount_cents": 50000 } } } } }, "get": { "operationId": "depositsList", "summary": "List deposits", "description": "Lists your deposits, newest first. Paginated. Unlike `GET /deposits/{id}`, the list does not check pending payments with the provider.", "tags": [ "Deposits" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return, between 1 and 100. Default 20.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "starting_after", "in": "query", "required": false, "description": "Cursor: the `id` of the last object of the previous page. Returns the objects that come after it.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only deposits with this status.", "schema": { "type": "string", "enum": [ "pending", "paid", "failed", "expired" ] }, "example": "paid" } ], "responses": { "200": { "description": "A page of deposits.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositList" }, "example": { "object": "list", "data": [ { "object": "deposit", "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b", "amount_cents": 50000, "currency": "BRL", "status": "paid", "br_code": null, "br_code_base64": null, "expires_at": "2026-10-18T14:00:00.000Z", "created_at": "2026-10-17T14:00:00.000Z", "paid_at": "2026-10-17T14:02:41.000Z" }, { "object": "deposit", "id": "3c8f1a20-6b7d-4e9f-8a1b-2c3d4e5f6a7b", "amount_cents": 100000, "currency": "BRL", "status": "paid", "br_code": null, "br_code_base64": null, "expires_at": "2026-10-11T09:00:00.000Z", "created_at": "2026-10-10T09:00:00.000Z", "paid_at": "2026-10-10T09:01:15.000Z" } ], "has_more": false } } } }, "400": { "description": "`invalid_limit`, `invalid_cursor`, `invalid_status`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_limit": { "summary": "`limit` must be an integer between 1 and 100.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_limit", "message": "limit must be an integer between 1 and 100.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_cursor": { "summary": "`starting_after` is not a UUID or is not an object of this list.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "starting_after is not a UUID or is not an object of this list.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_status": { "summary": "Unknown value in the `status` filter.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_status", "message": "Unknown value in the status filter.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/deposits/{id}": { "get": { "operationId": "depositsRetrieve", "summary": "Retrieve a deposit", "description": "Returns a deposit. While it is `pending`, this call also checks the payment with the PIX provider, so polling it every 5 to 10 seconds is how you learn that the balance was credited. A deposit of another reseller returns 404.", "tags": [ "Deposits" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Deposit id.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b" } ], "responses": { "200": { "description": "The deposit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" }, "example": { "object": "deposit", "id": "9b1e4c77-2f3a-4d8e-b5c6-0a1f2e3d4c5b", "amount_cents": 50000, "currency": "BRL", "status": "paid", "br_code": null, "br_code_base64": null, "expires_at": "2026-10-18T14:00:00.000Z", "created_at": "2026-10-17T14:00:00.000Z", "paid_at": "2026-10-17T14:02:41.000Z" } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "404": { "description": "`resource_missing`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.", "value": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/keys": { "post": { "operationId": "keysCreate", "summary": "Buy keys", "description": "Debits the wholesale price from your balance and creates the keys in one atomic operation. If the balance is not enough, nothing is charged or created (`402 insufficient_balance`). Up to 100 keys and 50 items per request. The response contains the full text of every key.", "tags": [ "Keys" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key per operation (a UUID is ideal), 1 to 255 visible ASCII characters. Retrying with the same key never charges twice.", "schema": { "type": "string" }, "example": "6c1f7d0e-4b9a-4a39-9d4e-2b8f0c7a1e55" } ], "responses": { "200": { "description": "Retry with the same `Idempotency-Key` and body: the original batch, nothing charged again.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Idempotent-Replayed": { "description": "`true` when the response is a replay.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyBatch" }, "example": { "object": "key_batch", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "total_cents": 2097, "balance_cents": 122903, "currency": "BRL", "keys": [ { "object": "key", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA", "key_prefix": "ACME-H150-AAAA", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null }, { "object": "key", "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b", "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB", "key_prefix": "ACME-H150-BBBB", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null }, { "object": "key", "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e", "key": "ACME-H600-CCCC-CCCC-CCCC-CCCC", "key_prefix": "ACME-H600-CCCC", "package_code": "H600", "hours": 600, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null } ] } } } }, "201": { "description": "The batch was bought.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyBatch" }, "example": { "object": "key_batch", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "total_cents": 2097, "balance_cents": 122903, "currency": "BRL", "keys": [ { "object": "key", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA", "key_prefix": "ACME-H150-AAAA", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null }, { "object": "key", "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b", "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB", "key_prefix": "ACME-H150-BBBB", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null }, { "object": "key", "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e", "key": "ACME-H600-CCCC-CCCC-CCCC-CCCC", "key_prefix": "ACME-H600-CCCC", "package_code": "H600", "hours": 600, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null } ] } } } }, "400": { "description": "`idempotency_key_required`, `invalid_idempotency_key`, `invalid_json`, `missing_items`, `invalid_items`, `too_many_items`, `invalid_package_code`, `invalid_quantity`, `duplicate_package`, `too_many_keys`, `package_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_required": { "summary": "POST without the `Idempotency-Key` header.", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_key_required", "message": "POST without the Idempotency-Key header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_idempotency_key": { "summary": "`Idempotency-Key` must have 1 to 255 visible ASCII characters, no spaces.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_idempotency_key", "message": "Idempotency-Key must have 1 to 255 visible ASCII characters, no spaces.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_json": { "summary": "The body is empty, is not JSON or is not a JSON object.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "The body is empty, is not JSON or is not a JSON object.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "missing_items": { "summary": "Send `items` (non-empty) or `package_code`.", "value": { "error": { "type": "invalid_request_error", "code": "missing_items", "message": "Send items (non-empty) or package_code.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_items": { "summary": "`items` must be an array of objects.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_items", "message": "items must be an array of objects.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "too_many_items": { "summary": "`items` accepts at most 50 entries.", "value": { "error": { "type": "invalid_request_error", "code": "too_many_items", "message": "items accepts at most 50 entries.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_package_code": { "summary": "`package_code` must look like `H150` (1 to 20 letters or digits).", "value": { "error": { "type": "invalid_request_error", "code": "invalid_package_code", "message": "package_code must look like H150 (1 to 20 letters or digits).", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_quantity": { "summary": "`quantity` must be an integer between 1 and 100.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_quantity", "message": "quantity must be an integer between 1 and 100.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "duplicate_package": { "summary": "The same package appears twice in `items`. Merge the quantities.", "value": { "error": { "type": "invalid_request_error", "code": "duplicate_package", "message": "The same package appears twice in items. Merge the quantities.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "too_many_keys": { "summary": "A request can create at most 100 keys in total.", "value": { "error": { "type": "invalid_request_error", "code": "too_many_keys", "message": "A request can create at most 100 keys in total.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "package_unavailable": { "summary": "The package does not exist or has no wholesale price. See `GET /packages`.", "value": { "error": { "type": "invalid_request_error", "code": "package_unavailable", "message": "The package does not exist or has no wholesale price. See GET /packages.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "402": { "description": "`insufficient_balance`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "summary": "The balance does not cover the total of the purchase. Nothing was charged or created.", "value": { "error": { "type": "insufficient_balance", "code": "insufficient_balance", "message": "The balance does not cover the total of the purchase. Nothing was charged or created.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "409": { "description": "`idempotency_key_reused`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_key_reused": { "summary": "The `Idempotency-Key` was already used with a different body. Use a new key for a new operation.", "value": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different body. Use a new key for a new operation.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "413": { "description": "`payload_too_large`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "payload_too_large": { "summary": "The body is larger than 24000 bytes.", "value": { "error": { "type": "invalid_request_error", "code": "payload_too_large", "message": "The body is larger than 24000 bytes.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } }, "requestBody": { "required": true, "description": "For a single package you can also send `{\"package_code\": \"H150\", \"quantity\": 10}` instead of `items`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseItem" }, "description": "What to buy: 1 to 50 objects `{package_code, quantity}`, each package at most once." } }, "required": [ "items" ] }, "example": { "items": [ { "package_code": "H150", "quantity": 2 }, { "package_code": "H600", "quantity": 1 } ] } } } } }, "get": { "operationId": "keysList", "summary": "List keys", "description": "Lists your keys, newest first. Paginated. Filter by status (`free` = not redeemed yet), package or purchase batch. Responses that include the key text are audited.", "tags": [ "Keys" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return, between 1 and 100. Default 20.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "example": 20 }, { "name": "starting_after", "in": "query", "required": false, "description": "Cursor: the `id` of the last object of the previous page. Returns the objects that come after it.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "`free` (not redeemed), `redeemed` or `all` (default; also includes revoked and suspended keys).", "schema": { "type": "string", "enum": [ "free", "redeemed", "all" ], "default": "all" }, "example": "free" }, { "name": "package_code", "in": "query", "required": false, "description": "Only keys of this package.", "schema": { "type": "string" }, "example": "H150" }, { "name": "batch_id", "in": "query", "required": false, "description": "Only keys of this purchase batch.", "schema": { "type": "string", "format": "uuid" }, "example": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21" } ], "responses": { "200": { "description": "A page of keys.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyList" }, "example": { "object": "list", "data": [ { "object": "key", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA", "key_prefix": "ACME-H150-AAAA", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null }, { "object": "key", "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b", "key": "ACME-H150-BBBB-BBBB-BBBB-BBBB", "key_prefix": "ACME-H150-BBBB", "package_code": "H150", "hours": 150, "status": "free", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": null } ], "has_more": true } } } }, "400": { "description": "`invalid_limit`, `invalid_cursor`, `invalid_status`, `invalid_package_code`, `invalid_batch_id`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_limit": { "summary": "`limit` must be an integer between 1 and 100.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_limit", "message": "limit must be an integer between 1 and 100.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_cursor": { "summary": "`starting_after` is not a UUID or is not an object of this list.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "starting_after is not a UUID or is not an object of this list.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_status": { "summary": "Unknown value in the `status` filter.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_status", "message": "Unknown value in the status filter.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_package_code": { "summary": "`package_code` must look like `H150` (1 to 20 letters or digits).", "value": { "error": { "type": "invalid_request_error", "code": "invalid_package_code", "message": "package_code must look like H150 (1 to 20 letters or digits).", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } }, "invalid_batch_id": { "summary": "`batch_id` must be a UUID.", "value": { "error": { "type": "invalid_request_error", "code": "invalid_batch_id", "message": "batch_id must be a UUID.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } }, "/keys/{id}": { "get": { "operationId": "keysRetrieve", "summary": "Retrieve a key", "description": "Returns one key by its `id` (UUID). To check whether a key you sold was redeemed, take its `id` from `GET /keys`: the key text never goes in the URL, where proxies and logs could record it. A key of another reseller, an unknown id or a malformed value all return the same 404. Responses that include the key text are audited.", "tags": [ "Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Key id (UUID), as returned by GET /keys or POST /keys.", "schema": { "type": "string" }, "example": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" } ], "responses": { "200": { "description": "The key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" }, "example": { "object": "key", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "ACME-H150-AAAA-AAAA-AAAA-AAAA", "key_prefix": "ACME-H150-AAAA", "package_code": "H150", "hours": 150, "status": "redeemed", "batch_id": "d2a7f3c1-4b5e-4f60-9a8b-7c6d5e4f3a21", "created_at": "2026-10-17T14:10:03.000Z", "redeemed_at": "2026-10-17T18:22:09.000Z" } } } }, "401": { "description": "`invalid_api_key`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "summary": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Missing, invalid, revoked or expired API key. The response is the same for every case.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "403": { "description": "`reseller_inactive`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reseller_inactive": { "summary": "The reseller account was revoked or removed.", "value": { "error": { "type": "permission_error", "code": "reseller_inactive", "message": "The reseller account was revoked or removed.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "404": { "description": "`resource_missing`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resource_missing": { "summary": "The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.", "value": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "The object does not exist or belongs to another reseller (same answer), or the endpoint does not exist.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Allow": { "description": "Methods supported by the endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "method_not_allowed": { "summary": "HTTP method not supported. See the `Allow` header.", "value": { "error": { "type": "invalid_request_error", "code": "method_not_allowed", "message": "HTTP method not supported. See the Allow header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "429": { "description": "`rate_limit_exceeded`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "summary": "Rate limit reached. Wait the number of seconds in the `Retry-After` header.", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Rate limit reached. Wait the number of seconds in the Retry-After header.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "500": { "description": "`internal_error`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "summary": "Unexpected error. Retry later; for POSTs, reuse the same `Idempotency-Key`.", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Unexpected error. Retry later; for POSTs, reuse the same Idempotency-Key.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } }, "503": { "description": "`service_unavailable`", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "service_unavailable": { "summary": "The service is temporarily unavailable. Retry with backoff.", "value": { "error": { "type": "api_error", "code": "service_unavailable", "message": "The service is temporarily unavailable. Retry with backoff.", "param": null }, "request_id": "req_5b0f3c9a1d2e4f6a8b7c9d0e1f2a3b4c" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "evb_live_...", "description": "Send your API key as `Authorization: Bearer evb_live_...`." } }, "headers": { "X-Request-Id": { "description": "Request id. Send it to support.", "schema": { "type": "string" } } }, "schemas": { "Balance": { "type": "object", "description": "The current wallet balance of the reseller.", "properties": { "object": { "type": "string", "enum": [ "balance" ], "description": "Always `balance`." }, "balance_cents": { "type": "integer", "minimum": 0, "description": "Available balance in cents of BRL." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Always `BRL`." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last balance change; `null` if the wallet was never used." } }, "required": [ "object", "balance_cents", "currency", "updated_at" ] }, "TokenInfo": { "type": "object", "description": "The API key used in the request.", "properties": { "name": { "type": "string", "description": "Name given to the key in the admin panel." }, "prefix": { "type": "string", "description": "First 8 characters after `evb_live_`, to identify the key." } }, "required": [ "name", "prefix" ] }, "Reseller": { "type": "object", "description": "The reseller that owns the API key.", "properties": { "object": { "type": "string", "enum": [ "reseller" ], "description": "Always `reseller`." }, "id": { "type": "string", "format": "uuid", "description": "Reseller id." }, "name": { "type": "string", "description": "Display name." }, "code": { "type": "string", "description": "Reseller code. It is the first part of the keys you buy." }, "status": { "type": "string", "enum": [ "active", "revoked" ], "description": "Only `active` resellers can call the API." }, "token": { "$ref": "#/components/schemas/TokenInfo", "description": "The API key used in this request." }, "balance": { "$ref": "#/components/schemas/Balance", "description": "Current balance." } }, "required": [ "object", "id", "name", "code", "status", "token", "balance" ] }, "Package": { "type": "object", "description": "A plan you can buy keys for, with your wholesale price.", "properties": { "object": { "type": "string", "enum": [ "package" ], "description": "Always `package`." }, "code": { "type": "string", "description": "Package code used in `POST /keys` (for example `H150`)." }, "hours": { "type": "integer", "description": "Farming hours granted by one key." }, "account_limit": { "type": "integer", "description": "Steam accounts the customer can farm at the same time." }, "price_cents": { "type": "integer", "description": "Your wholesale price per key, in cents of BRL." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Always `BRL`." } }, "required": [ "object", "code", "hours", "account_limit", "price_cents", "currency" ] }, "LedgerEntry": { "type": "object", "description": "An immutable balance movement.", "properties": { "object": { "type": "string", "enum": [ "ledger_entry" ], "description": "Always `ledger_entry`." }, "id": { "type": "string", "format": "uuid", "description": "Entry id (also the pagination cursor)." }, "kind": { "type": "string", "enum": [ "deposit", "key_purchase", "adjustment", "refund" ], "description": "`deposit` (PIX paid), `key_purchase` (keys bought), `adjustment` (manual, by the Evolution Boost team) or `refund`." }, "amount_cents": { "type": "integer", "description": "Signed amount: positive credits, negative debits." }, "balance_after_cents": { "type": "integer", "description": "Balance right after this movement." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Always `BRL`." }, "ref_type": { "type": [ "string", "null" ], "description": "What originated it, for example `deposit` or `key_batch`; usually `null` for adjustments." }, "ref_id": { "type": [ "string", "null" ], "description": "Id of the deposit or of the key batch." }, "description": { "type": [ "string", "null" ], "description": "Short human-readable description (may be in Portuguese)." }, "created_at": { "type": "string", "format": "date-time", "description": "When the movement happened." } }, "required": [ "object", "id", "kind", "amount_cents", "balance_after_cents", "currency", "ref_type", "ref_id", "description", "created_at" ] }, "Deposit": { "type": "object", "description": "A PIX charge that credits your balance once paid.", "properties": { "object": { "type": "string", "enum": [ "deposit" ], "description": "Always `deposit`." }, "id": { "type": "string", "format": "uuid", "description": "Deposit id." }, "amount_cents": { "type": "integer", "description": "Amount in cents of BRL." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Always `BRL`." }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "expired" ], "description": "`pending` until the PIX is paid; `paid` means the balance was credited; `failed` or `expired` will never be credited." }, "br_code": { "type": [ "string", "null" ], "description": "PIX copy-and-paste code. Only while `pending`." }, "br_code_base64": { "type": [ "string", "null" ], "description": "QR code as a PNG data URL (`data:image/png;base64,...`). Only while `pending`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the PIX charge expires (set by the payment provider)." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time." }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the payment was confirmed." } }, "required": [ "object", "id", "amount_cents", "currency", "status", "br_code", "br_code_base64", "expires_at", "created_at", "paid_at" ] }, "Key": { "type": "object", "description": "A license key that belongs to you.", "properties": { "object": { "type": "string", "enum": [ "key" ], "description": "Always `key`." }, "id": { "type": "string", "format": "uuid", "description": "Key id (also the pagination cursor)." }, "key": { "type": [ "string", "null" ], "description": "Full key text. `null` for old keys that cannot be recovered (use `key_prefix`)." }, "key_prefix": { "type": "string", "description": "First three parts of the key, safe to show." }, "package_code": { "type": "string", "description": "Package of the key." }, "hours": { "type": [ "integer", "null" ], "description": "Hours granted by the key." }, "status": { "type": "string", "enum": [ "free", "redeemed", "revoked", "suspended" ], "description": "`free` (not redeemed yet), `redeemed`, `revoked` or `suspended`." }, "batch_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Purchase batch that created the key." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time." }, "redeemed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a customer redeemed it." } }, "required": [ "object", "id", "key", "key_prefix", "package_code", "hours", "status", "batch_id", "created_at", "redeemed_at" ] }, "KeyBatch": { "type": "object", "description": "The result of a purchase: the keys created and the amount charged.", "properties": { "object": { "type": "string", "enum": [ "key_batch" ], "description": "Always `key_batch`." }, "batch_id": { "type": "string", "format": "uuid", "description": "Batch id. Use it in `GET /keys?batch_id=`." }, "total_cents": { "type": "integer", "description": "Total charged for the batch." }, "balance_cents": { "type": "integer", "description": "Balance after the purchase." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Always `BRL`." }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/Key" }, "description": "The keys created, with the full text." } }, "required": [ "object", "batch_id", "total_cents", "balance_cents", "currency", "keys" ] }, "PurchaseItem": { "type": "object", "description": "One line of a key purchase (request body only).", "properties": { "package_code": { "type": "string", "description": "Package code from `GET /packages`.", "examples": [ "H150" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of keys (default 1).", "examples": [ 10 ] } }, "required": [ "package_code", "quantity" ] }, "Error": { "type": "object", "description": "Error body returned with every non-2xx status.", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "What went wrong." }, "request_id": { "type": "string", "description": "Same value as the `X-Request-Id` header. Send it to support." } }, "required": [ "error", "request_id" ] }, "ErrorDetail": { "type": "object", "description": "Error details.", "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "invalid_request_error", "insufficient_balance", "rate_limit_error", "api_error" ], "description": "Broad category of the error." }, "code": { "type": "string", "description": "Stable machine-readable code (see the error table)." }, "message": { "type": "string", "description": "Human-readable message in English. Do not parse it." }, "param": { "type": [ "string", "null" ], "description": "Field or header that caused the error, when there is one." } }, "required": [ "type", "code", "message", "param" ] }, "PackageList": { "type": "object", "description": "A page of Package objects.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "has_more": { "type": "boolean", "description": "Whether there is another page after this one." } }, "required": [ "object", "data", "has_more" ] }, "LedgerEntryList": { "type": "object", "description": "A page of LedgerEntry objects.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "has_more": { "type": "boolean", "description": "Whether there is another page after this one." } }, "required": [ "object", "data", "has_more" ] }, "DepositList": { "type": "object", "description": "A page of Deposit objects.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" } }, "has_more": { "type": "boolean", "description": "Whether there is another page after this one." } }, "required": [ "object", "data", "has_more" ] }, "KeyList": { "type": "object", "description": "A page of Key objects.", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } }, "has_more": { "type": "boolean", "description": "Whether there is another page after this one." } }, "required": [ "object", "data", "has_more" ] } } } }