API reference
The OpenAPI document is the field-level reference: /v1/openapi.json. This page covers the conventions shared by account routes.
Base URL
Sandbox: https://api.rollstamp.example/v1. A live account uses the host issued with the account. Every path below is relative to that base.
Authentication
Send x-api-key: <key> or Authorization: Bearer <key> on account routes. The caller address must be on the key's allowlist. Documentation, portal token, signed file and media routes do not use an account key; the Overview lists those exceptions.
Errors
An error is JSON with success: false. The stable code and human message sit under error. Some errors add details, such as the path list from a schema check. Branch on the code, not on the message.
{
"success": false,
"error": {
"code": "invalid_request",
"message": "license_number is required."
}
}400 invalid_request: a field is missing or malformed; the message names it. The request was rejected before a change was saved.400 schema_validation_failed: the configuration does not match the schema.detailslists each path and message; nothing was saved.401 missing_api_key: no key was sent.403 invalid_api_keyorkey_disabled: fix the key or ask for a new one.403 ip_whitelist_requiredorip_not_allowed: ask for the calling server address to be added to the key.404: the path or record was not found. Many 404 codes name the record type; a genericnot_foundcan mean an unknown path, image or record.409: the write contradicts the current record, such as a duplicate open serial. The code names the reason.429 rate_limited,too_many_auth_failures,catalog_request_cooldown,order_volume_limitorfraud_limit_exceeded: wait forRetry-After, then retry with backoff.
Endpoint groups
- Compliance: acquisitions and dispositions, assemble and disassemble, exceptions, sync and ack.
- Maker Console: templates, series, next, reservations, serials, voids, scans, laser exports, builds, excise.
- Catalog and orders: products, inventory, quotes, orders, routing, carrier rates.
- Vetting and restrictions: checks, restriction checks, dealer directory, fraud reports.
- Webhooks: create, list, delete, deliveries.
- Vendors and portal: vendors and portal tokens.
- Support: conversations and messages.
- ERP and EDI: 850 out, inbound files, flat exports.
- MCP: connector settings and the MCP endpoint, which accepts an OAuth token or an account key.
Limits
Standard: 60 requests a minute, 10,000 a day. Pro: 300 a minute, 100,000 a day. Enterprise: 1,000 a minute, 1,000,000 a day. Successful responses to requests made with an account key carry the rate headers; a 429 includes Retry-After.