API reference

GET /v1/public/catalog

Published catalog for a seller

Public offers, access rules and how to request a key. Free and edge-cached; never counts against the seller's quota.

Auth No credentials

• 200 Public catalog projection → Envelope
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 404 Resource not found or not visible to this caller → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /v1/public/discover

Match public offers to a buying need

Auth No credentials

{
  "need": "inference",
  "region": "US"
}

• 200 Matching offers, most relevant first. An empty need returns every public offer. → Envelope
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /v1/public/pricing/calculate

Indicative price at public rates

Auth No credentials

{
  "offerId": "off_northstar-compute_growth",
  "seats": 5,
  "commitmentMonths": 12,
  "region": "US"
}

• 200 Itemized calculation and the policy decision → Envelope
• 404 Resource not found or not visible to this caller → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /v1/public/quote-verify

Check a signed quote or quote evidence bundle

Checks a compact JWS from a quote's signature.token, or from a seller's quote evidence export, against the keys at /.well-known/jwks.json. valid:true means PairRail signed exactly these facts. It does not say what the quote's status is now, and a signed quote is never a commitment (binding is false). An expired quote still verifies. The format is specified at /docs/quotes.

Auth No credentials

• 200 Verification result. When valid is false, reason is malformed, unexpected_header, unknown_key or bad_signature and no claims are returned.
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error

POST /v1/access-requests

Ask a seller for an agent key

Creates a pending request in the seller's inbox and returns a pickup token. A person on the seller's team approves or denies it. Free; never counted as a query. An optional Web Bot Auth signature is checked and shown to the seller with the request.

Auth No credentials

{
  "sellerId": "northstar-compute",
  "agentName": "Acme procurement agent",
  "contactEmail": "buyer@acme.example",
  "clientId": "acme-agent-1",
  "note": "Quoting GPU capacity for Q4"
}

• 200 A matching pending request already exists and is returned (reused is true, no new pickup token). → AccessRequestCreated
• 201 Request created → AccessRequestCreated
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error

GET /v1/access-requests/{accessRequestId}

Poll a request and claim the key once

Authenticate with the pickup token in the Authorization header (a pickupToken query parameter is refused). When the request is approved the response carries the key in secret exactly once; later polls return alreadyDelivered and no secret. If the request registered an agentPublicKey, the key arrives in secretEncrypted instead, encrypted to that key. The key must be claimed within 14 days of approval; after that the poll returns 410 and the key is never delivered.

Auth Pickup token (Bearer pickup_…)

• 200 Current status, and the key when it is first claimed → AccessRequestStatus
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 404 Resource not found or not visible to this caller → Error
• 410 The claim window passed before the key was picked up (ACCESS_REQUEST_CLAIM_EXPIRED). Request access again. → Error

GET /v1/catalog

Catalog visible to this key

Scope: catalog:read. Includes offers the seller discloses only to customers or partners when the key has that access level.

Auth Agent key (Bearer pat_…)

• 200 Catalog projection for the key's access level → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error

GET /v1/catalog/offers

Offers visible to this key

Scope: catalog:read.

Auth Agent key (Bearer pat_…)

• 200 Published offers allowed by the seller's disclosure policy → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error

POST /v1/discover

Match visible offers to a buying need

Scope: catalog:read.

Auth Agent key (Bearer pat_…)

• 200 Matching offers, most relevant first → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error

POST /v1/pricing/calculate

Price with this buyer's customer-tier rates

Scope: pricing:calculate. Deterministic and non-binding. Counts toward the key's pricing calls per hour (set by the seller), shared with MCP pricing_calculate calls made with the same key.

Auth Agent key (Bearer pat_…)

• 200 Itemized calculation and the policy decision. The decision says whether a quote would need approval, never the seller's approval caps. → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error

POST /v1/quote-requests

Create a non-binding quote

Scope: quote:request. Requires Idempotency-Key: retrying with the same key returns the original quote (200, replayed: true) instead of creating another. Above the seller's threshold the quote waits for a person on their deal desk. Splitting one order into smaller quotes does not avoid approval.

Auth Agent key (Bearer pat_…)

{
  "offerId": "off_northstar-compute_growth",
  "seats": 25,
  "commitmentMonths": 12,
  "region": "US",
  "need": "Team rollout in Q4",
  "buyer": {
    "company": "Acme Robotics",
    "name": "Procurement agent",
    "email": "procurement@acme.example"
  }
}

• 200 Same Idempotency-Key; the original quote is returned → Envelope
• 201 Quote created → Envelope
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error

GET /v1/quote-requests/{quoteRequestId}

Quote and approval status

Scope: quote:read. Poll this while a submitted quote waits on human approval. When the seller fulfills an executed quote later, the first read after that returns the credentials in data.entitlement, once; later reads show only its fingerprint and deliveredAt.

Auth Agent key (Bearer pat_…)

• 200 Quote with its approval outcome and next actions → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 404 Resource not found or not visible to this caller → Error

POST /v1/quote-requests/{quoteRequestId}/submit

Send an approval-required quote to the seller's deal desk

Scope: quote:request. A quote over the seller's threshold comes back approval-required with review.submittedAt: null, and nobody at the seller sees it until the buyer agent calls this. Call it only when the buyer wants the quote at its price. It opens the seller's approval, sends the approval.requested webhook and tells the seller's team; then poll the quote for the decision. Calling it again returns the same quote with data.replayed: true. Also served on MCP as quote_submit and on UCP, ACP, A2A and UAP as the submit action (A2A skill quote.submit) with quoteId in the body.

Auth Agent key (Bearer pat_…)

• 200 Quote sent to the deal desk (or already sent); status stays approval-required until a person decides → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 404 Resource not found or not visible to this caller → Error
• 409 The quote needs no approval or is finished (QUOTE_NOT_SUBMITTABLE), has expired (QUOTE_EXPIRED), or was priced on a catalog version that is no longer live (QUOTE_STALE). Request a new quote for the last two. → Error

POST /v1/quote-requests/{quoteRequestId}/execute

Hand an approved quote to the seller's billing

Scope: quote:execute, which sellers grant only on request. The quote must be within policy or approved by a person, and still match the live catalog, and the agent must present a delegated payment mandate its own human gave. Atlas refuses mandates that are expired, not yet valid, capped below the quote total, or bound to a different currency or quote. Mandates signed by an issuer the seller registered (ES256 on P-256, RS256 or EdDSA) are verified and must carry exp (at most 24 hours after issue), an integer maxAmountMinor and a jti unique per issuer. A mandate whose aud names another seller is refused (MANDATE_AUDIENCE_MISMATCH); sellers that require signed mandates also require aud (their seller id or slug) and quoteId. A mandate can name the agent allowed to spend it with azp set to its buyer key id (cred_…; other azp values, such as an OAuth client id, are ignored). A mandate signed by a registered issuer can also carry cnf: jkt, the RFC 7638 thumbprint of the agent's registered public key, or jwk, the key itself (cnf in unsigned tokens is ignored). Any other caller is refused (MANDATE_HOLDER_MISMATCH, MANDATE_HOLDER_KEY_UNKNOWN). Atlas then hands the quote to the seller's billing connector (Stripe, Chargebee or any billing system via signed webhook), which creates the invoice or quote there; the seller's processor stays the authority on the payment. The response has answerType: handed-off and data.handoff (provider, externalRef, status). Credentials the buyer bought are in data.entitlement and are returned only in this response: Atlas keeps a fingerprint, not the secret. When the buyer key has a registered agent key (or a signed mandate supplied cnf.jwk), data.entitlement.encrypted.jwe holds them encrypted to that key instead, and later quote reads return the same ciphertext.

Auth Agent key (Bearer pat_…)

• 200 Quote handed off; the processor or webhook outcome is returned → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 404 Resource not found or not visible to this caller → Error
• 409 The quote was already executed, or this signed mandate already paid for another quote (MANDATE_REPLAYED). → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 503 The seller has not connected a processor or webhook yet (SETTLEMENT_NOT_CONFIGURED). Back off and retry. → Error

GET /v1/readiness

Seller readiness profile

Scope: readiness:read.

Auth Agent key (Bearer pat_…)

• 200 Readiness score, dimensions, blockers and actions → Envelope
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error

GET /mcp

MCP server descriptor

The server's name, protocol versions and tools as JSON. A GET that accepts only text/event-stream gets 405: Atlas does not open a server-to-client stream. GET and POST are also served at /protocols/mcp.

Auth No credentials

• 200 MCP server descriptor
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 404 Resource not found or not visible to this caller → Error
• 405 The request accepted only text/event-stream
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /mcp

MCP endpoint (JSON-RPC 2.0)

Tools: catalog_browse, catalog_discover, pricing_calculate, readiness_inspect and request_catalog_access need no credentials; quote_request needs a seller-approved Bearer key. An Idempotency-Key header (or an idempotencyKey argument) on quote_request is optional: reusing one returns the original quote, and without one every call creates a new quote. server/discover and tools/list are free handshakes, and so are initialize and ping on 2025-11-25 and earlier (2026-07-28 drops both). A tool that runs and fails returns a result with isError: true and the error code (not counted); a missing key, plan limit or rate limit is a JSON-RPC error. Protocol version 2026-07-28 requests carry params._meta and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; initialize negotiates 2025-11-25 back to 2024-11-05. A key from another seller is refused on keyed tools (TENANT_DENIED) and ignored on public ones. A Web Bot Auth signature on quote_request or request_catalog_access is checked and recorded on the quote or access request.

Auth No credentials; Agent key (Bearer pat_…) for keyed tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "catalog_browse",
    "arguments": {
      "region": "US"
    }
  }
}

• 200 JSON-RPC result or error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 403 The key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error

GET /mcp/directory

Seller directory descriptor

The directory MCP server's name, endpoint, protocol versions and tools as JSON.

Auth No credentials

• 200 Directory server descriptor

POST /mcp/directory

Seller directory (MCP, JSON-RPC 2.0)

One MCP server over the public catalogs of every seller who chose to list in the directory. Tools: directory_list (sellers by name, limit and cursor) and directory_search (need, optional region, companySize, limit; up to three matching public offers per seller). Each entry gives the seller's own mcpUrl: price, ask for access and quote there. Entries carry status (live or sandbox) and quotes (live or rehearsal). No key and no sellerId. Never counted against any seller's plan; rate limited per client. Sellers are listed by name, and search results by how well offer text matches need, never by price. The same MCP versions and handshakes as /mcp.

Auth No credentials

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "directory_search",
    "arguments": {
      "need": "H100 GPUs for three months",
      "region": "US"
    }
  }
}

• 200 JSON-RPC result or error
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error

GET /.well-known/ucp

UCP business profile

The seller's Universal Commerce Protocol profile: the shopping service endpoint (/ucp/{sellerId}) and the catalog search and lookup capabilities. Also served at /protocols/ucp.

Auth No credentials

• 200 UCP profile (ucp.services, ucp.capabilities)
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /ucp/{sellerId}/catalog/search

UCP catalog search

Public products whose content matches query, with variants and indicative prices in UCP's product shape. An empty query returns every public product. Also served at /ucp/catalog/search?sellerId=.

Auth No credentials

{
  "query": "growth"
}

• 200 UCP response with products; ucp.status is error when nothing matches
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /ucp/{sellerId}/catalog/lookup

UCP catalog lookup

Products for each id: a product id or handle, or a variant id or sku, as search returns them. Ids with no match come back in messages with code not_found. Also served at /ucp/catalog/lookup?sellerId=.

Auth No credentials

{
  "ids": [
    "northstar-compute-compute-growth"
  ]
}

• 200 UCP response with products and any not_found messages
• 400 No ids given (INVALID_INPUT) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /ucp/{sellerId}/catalog/product

UCP product

One product by a product id or handle, or a variant id or sku. With no match, the response has a not_found message instead of product. Also served at /ucp/catalog/product?sellerId=.

Auth No credentials

{
  "id": "northstar-compute-compute-growth"
}

• 200 UCP response with product, or a not_found message
• 400 No id given (INVALID_INPUT) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /ucp/shopping

UCP shopping actions

Runs a PairRail action over UCP. The body is the protocol action envelope; with no action it prices. discover, price and readiness need no key. quote and execute need a seller-approved key with the same scope as REST (quote:request, quote:execute), and quote needs an Idempotency-Key header or arguments.idempotencyKey. A new quote is 201; a retry that returns an earlier quote is 200. Also served at /protocols/ucp/shopping.

Auth No credentials; Agent key (Bearer pat_…) for keyed actions

{
  "action": "price",
  "arguments": {
    "offerId": "off_northstar-compute_growth",
    "seats": 25,
    "commitmentMonths": 12,
    "region": "US"
  }
}

• 200 The action payload with protocol and action added; otherwise the same envelope REST returns for that action → Envelope
• 201 Quote created → Envelope
• 400 Missing or malformed input (SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED, QUOTE_ID_REQUIRED, or PROTOCOL_ACTION_UNKNOWN with the supported actions in details) → Error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED), or the key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 404 Resource not found or not visible to this caller → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

GET /protocols/ucp/products

UCP product feed

Every public product with its variants and indicative prices, in UCP's product shape.

Auth No credentials

• 200 Product feed (products, catalogVersion, binding)
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

GET /.well-known/agent-card.json

A2A agent card

The seller's A2A v1.0 agent card: the JSON-RPC interface URL, the skills (catalog.discover, pricing.calculate, readiness.inspect, quote.request, quote.execute) and capabilities (no streaming, no push notifications). Also served at /.well-known/agent.json, GET /a2a and /protocols/a2a.

Auth No credentials

• 200 A2A agent card
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /a2a

A2A JSON-RPC (SendMessage)

A2A v1.0 JSON-RPC. SendMessage runs the skill named in a data part (skill plus arguments); a message with only a text part runs catalog.discover with the text as the need. The answer is a ROLE_AGENT message whose data part is the same payload REST returns, with the REST status in metadata.status; HTTP is 200 on success.

quote.request and quote.execute need a seller-approved key. A quote uses a2a_ plus the messageId as its idempotency key unless arguments.idempotencyKey is set, so a retried message returns the same quote. Atlas creates no tasks: GetTask and CancelTask return -32001 (task not found), and streaming, task lists and push notifications are unsupported. Send A2A-Version: 1.0; a 0.3 slash-style method gets -32009. Errors use JSON-RPC codes with the PairRail error in error.data.

A body without jsonrpc is read as the protocol action envelope, as on /ucp/shopping. Also served at /protocols/a2a.

Auth No credentials; Agent key (Bearer pat_…) for keyed actions

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-1",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "skill": "pricing.calculate",
            "arguments": {
              "offerId": "off_northstar-compute_growth",
              "seats": 25,
              "commitmentMonths": 12,
              "region": "US"
            }
          }
        }
      ]
    }
  }
}

• 200 JSON-RPC result (result.message) or, for the envelope, the action payload
• 400 JSON-RPC error for bad params, an unknown skill or method, or an unsupported version
• 401 JSON-RPC error; error.data.code is AUTH_REQUIRED or INVALID_CREDENTIAL
• 402 JSON-RPC error; error.data.code is PROTOCOL_NOT_ALLOWED (seller on Sandbox)
• 403 JSON-RPC error; error.data.code is PROTOCOL_DISABLED, INSUFFICIENT_SCOPE or TENANT_DENIED
• 404 JSON-RPC error for task lookups (-32001), or an unknown seller or offer
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 JSON-RPC error; error.data.code is AGENT_ACCESS_PAUSED

GET /protocols/acp

ACP descriptor

Agentic Commerce Protocol (2026-04-17) line items for each public offer at its indicative unit price. PairRail detail that ACP's LineItem has no field for (meters, tiers) is in pairrail.line_items. Also lists the PairRail endpoints for pricing and quotes. Atlas does not run ACP checkout sessions: quotes and execution go through PairRail actions.

Auth No credentials

• 200 ACP descriptor (line_items, offers, endpoints, authority)
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /protocols/acp

ACP actions

Runs a PairRail action over ACP, with the same envelope, keys and status codes as /ucp/shopping. With no action it prices. checkout and confirm are read as execute.

Auth No credentials; Agent key (Bearer pat_…) for keyed actions

{
  "action": "discover",
  "arguments": {
    "need": "compute"
  }
}

• 200 The action payload with protocol and action added; otherwise the same envelope REST returns for that action → Envelope
• 201 Quote created → Envelope
• 400 Missing or malformed input (SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED, QUOTE_ID_REQUIRED, or PROTOCOL_ACTION_UNKNOWN with the supported actions in details) → Error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED), or the key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 404 Resource not found or not visible to this caller → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

GET /protocols/uap

UAP / Beckn descriptor

A Beckn-style provider descriptor: the subscriber, items with indicative prices, and which actions are public (search, select) and which need a seller-approved key (init, confirm). Also served at /protocols/beckn.

Auth No credentials

• 200 UAP descriptor (subscriber, items, accessModel, endpoints)
• 400 Missing or malformed input (for example SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED); details links the seller's MCP endpoint → Error
• 404 Resource not found or not visible to this caller → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error

POST /protocols/uap

UAP / Beckn actions

Runs a PairRail action with Beckn action names: search discovers, select prices (the default), init quotes and confirm executes. The body is the protocol action envelope, not a Beckn context and message. Keys and status codes are as on /ucp/shopping. Also served at /protocols/beckn.

Auth No credentials; Agent key (Bearer pat_…) for keyed actions

{
  "action": "select",
  "arguments": {
    "offerId": "off_northstar-compute_growth",
    "seats": 25,
    "commitmentMonths": 12,
    "region": "US"
  }
}

• 200 The action payload with protocol and action added; otherwise the same envelope REST returns for that action → Envelope
• 201 Quote created → Envelope
• 400 Missing or malformed input (SELLER_ID_REQUIRED, IDEMPOTENCY_REQUIRED, QUOTE_ID_REQUIRED, or PROTOCOL_ACTION_UNKNOWN with the supported actions in details) → Error
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 402 The seller is on Sandbox, which serves MCP and REST only (PROTOCOL_NOT_ALLOWED) → Error
• 403 The seller turned this rail off (PROTOCOL_DISABLED), or the key lacks the scope (INSUFFICIENT_SCOPE) or belongs to another seller (TENANT_DENIED) → Error
• 404 Resource not found or not visible to this caller → Error
• 422 Commercial validation failed (for example INVALID_COMMITMENT, POLICY_DENIED, QUOTE_NOT_EXECUTABLE) → Error
• 429 Too many requests, or a key's velocity limit was reached. Honor Retry-After. VELOCITY_LIMIT details name the window and never give counts, limits or amounts. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → Error