# RollStamp API - reference for coding agents

Base: /v1. Auth: x-api-key (or "Authorization: Bearer <key>") on account routes. Public exceptions are /v1/openapi.json, /v1/docs, /v1/docs/guide, /v1/llms.txt, /v1/_exports/*, /v1/_files/ffl-documents/* and /v1/_media/*. /v1/portal/* uses a vendor portal token. The MCP endpoint at /mcp accepts an OAuth access token or an account API key; /oauth/* and the OAuth discovery paths are public.
The caller address must be on the key allowlist. The key can place orders and make other writes: server-side only.
Envelope: {"success":true,"data":...} or {"success":false,"error":{"code","message","details?"}}. Branch on error.code.
The API answers 403 for a path outside /v1, except /mcp, /oauth/* and /.well-known/oauth-*. Website pages, including /portal and /support, come from the site build, not these API routes.

## Rules that matter
- PUT /v1/config replaces the whole document. GET it, edit, PUT it back. Masked secrets ("********") stay unchanged when sent back.
- Products only come from sources that are active and passed POST /v1/config/validate. Otherwise 409 no_active_distributors / no_validated_distributors.
- distid is a code (RSR, LIP, DAV, TSW), never a number.
- order_id is your idempotency key: 409 duplicate_order means it was placed. Do not retry with a new id.
- GET /v1/products/catalog for a full sync (parquet, once per 20 min, last_version polls free); search for interactive lookups (up to 100 per page, default 50).
- Fraud matches are signals to review. Strong signals: shipping_address_1, billing_address_1, email, phone. A shipping address does not count when the order ships to an FFL.
- Honor Retry-After on 429. Limits per tier (minute/day): standard 60/10000, pro 300/100000, enterprise 1000/1000000.
- FastBound is the legal record by default. On a FastBound license, every committed change queues for FastBound. The sync queue, ack routes and the adapter that drains the queue are built; the adapter stays off until the FastBound account number, API key and audit user are set, along with a RollStamp API key. This build has none configured.

## Endpoints
GET  /v1/ping                       key check
GET  /v1/account                    tier, limits, allowed IPs, configured sources
GET  /v1/usage                      today, this month, by endpoint, last 7 days
POST /v1/compliance/licenses        add a license and its book
GET  /v1/compliance/licenses        list licenses and their system of record
POST /v1/compliance/licenses/{id}/system-of-record  switch to rollstamp (needs counsel sign-off and no queued FastBound changes)
POST /v1/compliance/acquisitions    RECEIVE | MANUFACTURE | IMPORT | FOUND
POST /v1/compliance/dispositions    nine types; pending:true only where allowed
POST /v1/compliance/dispositions/{id}/commit | /cancel
POST /v1/compliance/assemble | /disassemble
GET  /v1/compliance/items | /items/{id} | /book | /transactions | /exceptions
POST /v1/compliance/items/{id}/corrections  reason and recorded_by required
GET  /v1/compliance/sync            FastBound queue
POST /v1/compliance/sync/{id}/ack   acknowledge one entry
POST /v1/manufacturing/templates    product template
POST /v1/manufacturing/series       serial series (Type 07/10)
GET  /v1/manufacturing/series/{id}/next  preview next serial
POST /v1/manufacturing/series/{id}/reservations  reserve up to 1,000
GET  /v1/manufacturing/serials      filter by license, series, batch, model or state
POST /v1/manufacturing/serials/{id}/void  reason and recorded_by required
POST /v1/manufacturing/scans        mark a reserved serial
GET  /v1/manufacturing/scans        successful and refused scans
GET  /v1/manufacturing/laser-jobs/export.csv | .txt
POST /v1/manufacturing/builds       complete a build into the book
POST /v1/manufacturing/excise/sales | GET .../sales | .../count | .../worksheet
GET  /v1/distributors               registry: distid, config_schema, default_config
GET  /v1/config                     account configuration (secrets masked)
PUT  /v1/config[?validate=true]     replace it; schema_validation_failed details=[{path,message}]
GET  /v1/config/schema              JSON Schema (draft-04), no envelope
POST /v1/config/validate            {} = live check; {"configuration":{...}} = dry run
GET  /v1/products/search            q upc sku distributor manufacturer product_class category min_price max_price in_stock drop_ship_only ffl_required sort page page_size (max 100)
GET  /v1/products/facets            manufacturers, categories, product_classes
GET  /v1/products/catalog           last_version expires_in(1200-3600) -> parquet url
GET  /v1/products/{upc}             every offer for one UPC
GET  /v1/products/{upc}/history     3 months of stock and cost changes
GET  /v1/analytics/{metric}         top-products | on-sale | margin-opportunities | trending | new-arrivals | newly-available | price-gaps; window=7d|30d|60d|90d limit<=200
GET  /v1/ffls                       zip radius(1-50) name -> up to 150 dealers
GET  /v1/ffls/{license}             one dealer; X matches any character
GET  /v1/ffls/{license}/documents/{ffl|sot}  license on your orders, document on file
POST /v1/restrictions/check         shipping + up to 100 items
POST /v1/orders/quote               items -> best source, alternatives, plan
POST /v1/orders                     order_id, customer, items, ffl, sourcing_mode?
GET  /v1/orders | /orders/{order_id} | /fulfillment/history
POST /v1/fraud/check                address / email / phone signals
POST /v1/fraud/reports | DELETE /v1/fraud/reports
GET  /v1/orders/{order_id}/routing  per line: chosen source, rule, reason, candidates
GET  /v1/inventory/{sku}            UPC or source SKU -> stock and cost at each source that carries it
POST /v1/shipping/rates             {origin_zip, destination_zip, weight_lb, dimensions?, contents?(general|handgun|long_gun|ammunition), residential?, declared_value?} sample rate tables
POST /v1/orders/quote               also accepts carrier_rates:true + destination_zip -> plan.orders[].carrier_rates
POST /v1/vetting/checks             {type(ffl_dealer|vendor|ship_to), license_number?, business_name?, premise_address?|ship_to_address?, registration_state?, reference?, recheck?} -> processing, done ~5s later
GET  /v1/vetting/checks             status reference limit offset
GET  /v1/vetting/checks/{id}        status processing|verified|needs_review|failed, confidence, flags, evidence
POST /v1/webhooks                   {url(https; http only with private testing), events[]} -> secret shown once. Events: vetting.check.completed vetting.license.expiring order.submitted order.shipped order.delivered vendor.inventory.updated support.message.created
GET  /v1/webhooks                   | DELETE /v1/webhooks/{id} | GET /v1/webhooks/{id}/deliveries | POST /v1/webhooks/{id}/test
GET  /v1/orders/{order_id}/edi      X12 850 per distributor/vendor order
POST /v1/edi/inbound                {"x12":"..."} reads 855 856 810 846, returns results + 997
GET  /v1/edi/settings               | PUT {isa_sender_id, isa_qualifier, test_mode, partners}
GET  /v1/erp/export                 type(orders|purchase_order_lines|shipments|invoices) format(json|csv) since
POST /v1/vendors                    {name, contact_email?, shipping_flat?, edi_id?} -> portal_token shown once
GET  /v1/vendors                    | PUT /v1/vendors/{id} {status|shipping_flat|name} | POST /v1/vendors/{id}/token | GET|PUT /v1/vendors/{id}/inventory
GET  /v1/portal/me                  vendor routes: Authorization: Bearer <portal token> (no API key, no IP allowlist)
GET  /v1/portal/orders              status(open|shipped) | POST /v1/portal/orders/{po}/tracking {carrier, tracking_number} | GET|PUT /v1/portal/inventory {csv|items}
POST /v1/support/conversations      {message, subject?} | GET list | GET {id} | POST {id}/messages | POST {id}/close
GET  /v1/mcp/settings               | PUT {enabled, allow_writes, ship_target_hours} | DELETE /v1/mcp/connections/{id}
POST /mcp                           MCP server (JSON-RPC). Auth: OAuth 2.1 + PKCE (discovery at /.well-known/oauth-authorization-server) or "Authorization: Bearer <api key>" (or "x-api-key"). Off until enabled in settings.

## Example values that work in this sandbox
Key: fflsbx_std_9f3k2m7q4t (allowed from 127.0.0.1)
Firearm: upc 643740108515, distid LIP, distsku LP108515
Accessory: upc 720868151439, distid TSW, distsku 61439
FFL near 37201: 4-37-201-01-8K-70207

## Errors
400 invalid_parameter / invalid_request / invalid_json / invalid_upc: The body or a field is missing or malformed. The request is rejected before any change.
400 schema_validation_failed: Configuration rejected; details lists every {path, message}. Nothing was saved.
400 missing_strong_signal: A fraud call needs an address line, an email or a phone.
401 missing_api_key: Send the x-api-key header.
403 invalid_api_key / key_disabled: Unknown, disabled or cancelled key.
403 ip_whitelist_required: The key has no registered server IPs yet.
403 ip_not_allowed: This caller address is not on the key allowlist.
403 ffl_not_associated_with_order: License documents are only for FFLs used by your own orders.
404 not_found / product_not_found / ffl_not_found / order_not_found / report_not_found: No match: an unknown path, a missing image, or a record not on this account.
409 no_active_distributors / no_validated_distributors: Activate sources, then check their credentials.
409 duplicate_order: That order_id was already placed. Do not retry with a new id.
400 invalid_ffl: The dealer license is malformed, unknown or inactive.
409 sourcing_unavailable: The named source cannot fill a line.
409 restricted_destination / fulfillment_not_configured: The order cannot ship as requested.
409 validation_failed: A save would remove too much of the catalog.
413 payload_too_large: Bodies are capped at 1 MB.
429 rate_limited: Wait Retry-After seconds, then retry with backoff.
429 catalog_request_cooldown: One catalog download per 20 minutes; send last_version to poll for free.
429 order_volume_limit / fraud_limit_exceeded: The order or fraud cap was reached.
401 invalid_vendor_token / unauthorized / invalid_token: Portal or connector credentials are missing, wrong or expired.
403 vendor_disabled / mcp_disabled / bulk_changes_not_allowed: The vendor, the connector or bulk changes are switched off for the account.
404 check_not_found / webhook_not_found / vendor_not_found / conversation_not_found / connection_not_found: Nothing with that id on your account.
400 invalid_edi: The X12 text could not be read (ISA segment or ST/SE pairs).
409 webhook_limit / vendor_limit / too_many_open_conversations / conversation_closed / preview_stale: A limit was reached, or the thing changed since you looked.
500 internal_error: Retry with backoff.
