Connect an agent to a PairRail catalog

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. → 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. → Error
• 503 The seller paused agent access (AGENT_ACCESS_PAUSED) → 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.

Auth No credentials

{
  "sellerId": "northstar-compute",
  "agentName": "Acme procurement agent",
  "contactEmail": "[email protected]",
  "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. → Error

GET /v1/access-requests/{accessRequestId}

Poll a request and claim the key once

Authenticate with the pickup token. When the request is approved the response carries the key in secret exactly once; later polls return alreadyDelivered and no secret.

Auth Pickup token (Bearer pickup_…)

• 200 Current status, and the key when it is first claimed → AccessRequestStatus
• 401 Missing, invalid, expired or revoked credential (AUTH_REQUIRED, INVALID_CREDENTIAL) → Error
• 404 Resource not found or not visible to this caller → 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.

Auth Agent key (Bearer pat_…)

• 200 Itemized calculation and the policy decision → 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. → 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.

Auth Agent key (Bearer pat_…)

{
  "offerId": "off_northstar-compute_growth",
  "seats": 25,
  "commitmentMonths": 12,
  "region": "US",
  "need": "Team rollout in Q4"
}

• 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. → Error

GET /v1/quote-requests/{quoteRequestId}

Quote and approval status

Scope: quote:read. Poll this while a quote waits on human approval.

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}/execute

Hand an approved quote to the seller's billing

Scope: quote:execute, which sellers grant only on request. The quote must be approved 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. 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).

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

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 and an Idempotency-Key header. initialize, tools/list and ping are free handshakes. A key from another seller is refused on keyed tools (TENANT_DENIED) and ignored on public ones.

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