{ "openapi": "3.1.0", "info": { "title": "AgentOutpost API", "description": "The procurement layer for the agent economy.\n\n**Private beta: an invite key is required** on the catalog, quote, order and MCP routes: `Authorization: Bearer ao___`; without one you get `401 INVITE_REQUIRED`. Request a key with `POST /waitlist` or the form at `/`. Callers are identified by their invite key for rate limits (HTTP 429 with `Retry-After` when exceeded). Send `X-Agent-Name` and `X-Agent-Version` for attribution.\n\nFlow: `POST /resolve-intent` (or `GET /products`) → `POST /quote` → `POST /orders`, which returns `payment` terms and charges nothing → `POST /orders/{id}/pay` with a payment credential issued by the agent's platform (a hold is authorized and captured when the supplier confirms) → `GET /orders/{id}`. The same capabilities are exposed as MCP tools at `POST /mcp`. Agent guide: `/llms.txt`.", "license": { "name": "UNLICENSED", "identifier": "UNLICENSED" }, "version": "0.1.0" }, "paths": { "/admin/waitlist": { "get": { "tags": [ "access" ], "summary": "Waitlist signups, newest first.", "operationId": "list", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistList" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "admin_key": [] } ] } }, "/analytics/summary": { "get": { "tags": [ "analytics" ], "summary": "Quote volume, conversion, SKU popularity and agent usage. Admin keys only.", "operationId": "analytics_summary", "parameters": [ { "name": "days", "in": "query", "description": "Look-back window in days (1-90, default 30).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSummary" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "admin_key": [] } ] } }, "/health": { "get": { "tags": [ "system" ], "operationId": "health", "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/orders": { "post": { "tags": [ "purchasing" ], "summary": "Create an order from a quote and receive payment terms (`payment`: paymentId, exact amount,\ncurrency, expiry and accepted credentials). Nothing is charged by this call; pay with\n`POST /orders/{id}/pay`. Idempotent per quote and per `Idempotency-Key`.", "operationId": "create_order", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Retry-safe key", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Existing order returned for a retried request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "201": { "description": "Order created with payment terms; nothing is charged yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Quote expired or idempotency key reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Payment temporarily unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/orders/{id}": { "get": { "tags": [ "purchasing" ], "summary": "Get an order, its status and payment status, and (while unpaid) its payment terms.", "operationId": "get_order", "parameters": [ { "name": "id", "in": "path", "description": "Order id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/orders/{id}/cancel": { "post": { "tags": [ "purchasing" ], "summary": "Cancel an order that has not been paid. Paid orders need a refund through support.", "operationId": "cancel_order", "parameters": [ { "name": "id", "in": "path", "description": "Order id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional reason", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CancelOrderRequest" }, { "type": "null" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Already paid, cancelled or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/orders/{id}/pay": { "post": { "tags": [ "purchasing" ], "summary": "Pay an order by echoing its payment terms together with a payment credential issued by the\nagent's platform. A hold is authorized (nothing is captured yet) and the order becomes\n`PENDING`; the hold is captured once the supplier confirms and released if placement fails.\nA mismatch with the terms is refused before the provider is called. Retrying a paid order\nreturns it unchanged.", "operationId": "pay_order", "parameters": [ { "name": "id", "in": "path", "description": "Order id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Hold authorized; the order is PENDING", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment declined (PAYMENT_DECLINED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Terms mismatch or expired, payment in progress, or the order is not payable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Payment temporarily unavailable; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/products": { "get": { "tags": [ "catalog" ], "summary": "List the standardized catalog with published prices.", "operationId": "list_products", "parameters": [ { "name": "category", "in": "query", "description": "Filter by category, e.g. `BATTERIES`.", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive text search over SKU, name and description.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/products/{sku}": { "get": { "tags": [ "catalog" ], "summary": "Get one product by SKU.", "operationId": "get_product", "parameters": [ { "name": "sku", "in": "path", "description": "Standardized SKU", "required": true, "schema": { "type": "string" }, "example": "AA_BATTERY_STANDARD_4" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/quote": { "post": { "tags": [ "purchasing" ], "summary": "Price a basket at published prices for delivery to a US ZIP code. Binding for 30 minutes.", "operationId": "create_quote", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown SKU", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "No supplier can fulfil an item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/resolve-intent": { "post": { "tags": [ "catalog" ], "summary": "Map a plain-language need to catalog SKUs.", "operationId": "resolve_intent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIntentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIntentResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "invite_key": [] } ] } }, "/waitlist": { "post": { "tags": [ "access" ], "summary": "Ask for a private-beta invite key. Answers the same whether or not the address was already\nlisted.", "operationId": "join", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "AcceptedCredentialResponse": { "type": "object", "description": "A kind of payment credential the server can redeem.", "required": [ "type" ], "properties": { "networkBusinessProfile": { "type": [ "string", "null" ], "description": "For Stripe shared payment tokens: the seller profile the token must be scoped to." }, "type": { "type": "string", "description": "`stripe_shared_payment_token` or `mock` (development only)." } } }, "AddressResponse": { "type": "object", "required": [ "recipient", "line1", "city", "region", "postalCode", "country" ], "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "recipient": { "type": "string" }, "region": { "type": "string" } } }, "AgentStat": { "type": "object", "required": [ "agentName", "agentKind", "quotes", "orders", "paidOrders" ], "properties": { "agentKind": { "type": "string" }, "agentName": { "type": "string" }, "orders": { "type": "integer", "format": "int64", "minimum": 0 }, "paidOrders": { "type": "integer", "format": "int64", "minimum": 0 }, "quotes": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AnalyticsSummary": { "type": "object", "description": "Business metrics over a time window.", "required": [ "windowDays", "quotes", "orders", "paidOrders", "quoteToPaidConversion", "checkoutCompletion", "grossMerchandiseValue", "topOrderedSkus", "topQuotedSkus", "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentStat" } }, "checkoutCompletion": { "type": "number", "format": "double", "description": "paid orders / orders, 0.0-1.0: how often payment terms turn into a payment." }, "grossMerchandiseValue": { "type": "number", "format": "double" }, "orders": { "type": "integer", "format": "int64", "description": "Orders created (payment terms issued).", "minimum": 0 }, "paidOrders": { "type": "integer", "format": "int64", "minimum": 0 }, "quoteToPaidConversion": { "type": "number", "format": "double", "description": "paid orders / quotes, 0.0-1.0." }, "quotes": { "type": "integer", "format": "int64", "minimum": 0 }, "topOrderedSkus": { "type": "array", "items": { "$ref": "#/components/schemas/SkuStat" } }, "topQuotedSkus": { "type": "array", "items": { "$ref": "#/components/schemas/SkuStat" } }, "windowDays": { "type": "integer", "format": "int32", "minimum": 0 } } }, "BuyerRequest": { "type": "object", "description": "Who is buying; receives the payment receipt.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Receipt and order-update email address." }, "name": { "type": [ "string", "null" ], "description": "Defaults to the shipping recipient." } }, "additionalProperties": false }, "CancelOrderRequest": { "type": "object", "description": "Optional body for `POST /orders/{id}/cancel`.", "properties": { "reason": { "type": [ "string", "null" ], "description": "Free-text reason, recorded in logs." } } }, "CreateOrderRequest": { "type": "object", "required": [ "quoteId" ], "properties": { "idempotencyKey": { "type": [ "string", "null" ], "description": "Alternative to the `Idempotency-Key` header." }, "quoteId": { "type": "string", "description": "Id from `POST /quote`.", "example": "qt_0192f1b07d9e7c3a9b1e5d2c4a8f6e10" } } }, "CreateQuoteRequest": { "type": "object", "required": [ "items", "postalCode" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteItem" } }, "postalCode": { "type": "string", "description": "5-digit US ZIP code of the delivery address.", "example": "46580" } } }, "ErrorBody": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code, e.g. `SKU_NOT_FOUND`, `QUOTE_EXPIRED`.", "example": "SKU_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable explanation. Do not parse; it may change." }, "request_id": { "type": [ "string", "null" ], "description": "Correlates with server logs and traces." } } }, "ErrorResponse": { "type": "object", "description": "Uniform error envelope for every non-2xx response.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } } }, "HealthResponse": { "type": "object", "required": [ "status", "version" ], "properties": { "status": { "type": "string" }, "version": { "type": "string" } } }, "IntentMatchResponse": { "type": "object", "required": [ "sku", "name", "confidence", "reason" ], "properties": { "confidence": { "type": "number", "format": "float", "description": "0.0-1.0" }, "name": { "type": "string" }, "reason": { "type": "string" }, "sku": { "type": "string" } } }, "OrderLineResponse": { "type": "object", "required": [ "sku", "name", "quantity", "unitPrice", "lineTotal" ], "properties": { "lineTotal": { "type": "number", "format": "double" }, "name": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "sku": { "type": "string" }, "unitPrice": { "type": "number", "format": "double" } } }, "OrderResponse": { "type": "object", "required": [ "orderId", "quoteId", "status", "nextAction", "lines", "subtotal", "shipping", "tax", "total", "currency", "estimatedDeliveryDays", "createdAt", "updatedAt" ], "properties": { "capturedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the hold was captured, after the supplier confirmed the order." }, "createdAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "estimatedDeliveryDays": { "type": "integer", "format": "int32", "minimum": 0 }, "lastPaymentError": { "type": [ "string", "null" ], "description": "The most recent payment decline or capture failure, if any." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLineResponse" } }, "nextAction": { "type": "string", "description": "What the agent should do now, in plain language." }, "orderId": { "type": "string", "description": "Unguessable; anyone holding it can view or cancel the order. Share it only with the buyer." }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the payment hold was authorized." }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/PaymentTermsResponse", "description": "Payment terms to echo when paying. Present only while `status` is `AWAITING_PAYMENT` and\nthe order has terms." }, { "type": "null" } ] }, "paymentStatus": { "type": [ "string", "null" ], "description": "`AUTHORIZED` (hold placed), `CAPTURED` (charged after the supplier confirmed), `RELEASED`\n(hold cancelled, nothing charged) or `FAILED` (capture failed; contact support). Absent\nuntil a hold is authorized.", "example": "AUTHORIZED" }, "quoteId": { "type": "string" }, "shipping": { "type": "number", "format": "double" }, "shippingAddress": { "oneOf": [ { "$ref": "#/components/schemas/AddressResponse", "description": "Supplied when paying." }, { "type": "null" } ] }, "status": { "type": "string", "description": "`AWAITING_PAYMENT`, `PENDING`, `CONFIRMED`, `FULFILLED`, `DELIVERED`, `CANCELLED` or\n`EXPIRED`.", "example": "AWAITING_PAYMENT" }, "subtotal": { "type": "number", "format": "double" }, "tax": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PayOrderRequest": { "type": "object", "description": "Body for `POST /orders/{id}/pay`: echo the order's payment terms and supply a credential.", "required": [ "paymentId", "amount", "currency", "credential", "buyer", "shippingAddress" ], "properties": { "amount": { "type": "number", "format": "double", "description": "Amount in dollars; must equal the order total." }, "amountCents": { "type": [ "integer", "null" ], "format": "int64", "description": "Amount in cents; preferred over `amount` when given, as it avoids float rounding. If both\nare sent they must agree, otherwise the request is `PAYMENT_TERMS_MISMATCH`." }, "buyer": { "$ref": "#/components/schemas/BuyerRequest" }, "credential": { "$ref": "#/components/schemas/PaymentCredentialRequest" }, "currency": { "type": "string", "description": "`USD`." }, "paymentId": { "type": "string", "description": "`payment.paymentId` from the order." }, "shippingAddress": { "$ref": "#/components/schemas/ShippingAddressRequest" } }, "additionalProperties": false }, "PaymentCredentialRequest": { "type": "object", "description": "The payment credential issued by the buyer's platform.", "required": [ "type", "token" ], "properties": { "token": { "type": "string", "description": "The credential itself, for example a Stripe shared payment token (`spt_...`). It is a\nsecret: never log it." }, "type": { "type": "string", "description": "`stripe_shared_payment_token` or `mock` (development only). Must be one of the order's\n`payment.acceptedCredentials`." } }, "additionalProperties": false }, "PaymentTermsResponse": { "type": "object", "description": "The handshake: what the buyer agent must echo when it pays.", "required": [ "paymentId", "amount", "amountCents", "currency", "expiresAt", "acceptedCredentials" ], "properties": { "acceptedCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/AcceptedCredentialResponse" }, "description": "Credential types the server can redeem; present one of these when paying." }, "amount": { "type": "number", "format": "double", "description": "Exact amount to pay, in dollars." }, "amountCents": { "type": "integer", "format": "int64", "description": "Exact amount to pay, in cents. Prefer this over `amount` to avoid rounding." }, "currency": { "type": "string", "description": "ISO 4217 currency code; only `USD` is supported." }, "expiresAt": { "type": "string", "format": "date-time", "description": "The terms stop being payable at this time." }, "paymentId": { "type": "string", "description": "Echo this when paying." } } }, "ProductListResponse": { "type": "object", "required": [ "products", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductResponse" } } } }, "ProductResponse": { "type": "object", "description": "A standardized catalog product.", "required": [ "id", "sku", "name", "category", "unit_size", "unit_of_measure", "price", "currency", "description", "active", "created_at", "updated_at" ], "properties": { "active": { "type": "boolean" }, "category": { "type": "string", "example": "BATTERIES" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "example": "USD" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string", "example": "AA Battery Standard 4 Pack" }, "price": { "type": "number", "format": "double", "description": "Published list price per SKU unit; quotes use this price.", "example": 5.99 }, "sku": { "type": "string", "description": "Stable identifier to quote and order by.", "example": "AA_BATTERY_STANDARD_4" }, "unit_of_measure": { "type": "string", "example": "battery" }, "unit_size": { "type": "integer", "format": "int32", "description": "Number of units in one purchasable SKU.", "example": 4, "minimum": 0 }, "updated_at": { "type": "string", "format": "date-time" } } }, "QuoteItem": { "type": "object", "required": [ "sku", "quantity" ], "properties": { "quantity": { "type": "integer", "format": "int32", "description": "Number of SKU units (1-1000).", "example": 1, "maximum": 1000, "minimum": 1 }, "sku": { "type": "string", "description": "Standardized SKU, e.g. `AA_BATTERY_STANDARD_4`.", "example": "AA_BATTERY_STANDARD_4" } } }, "QuoteLineResponse": { "type": "object", "required": [ "sku", "name", "quantity", "unitPrice", "lineTotal" ], "properties": { "lineTotal": { "type": "number", "format": "double" }, "name": { "type": "string" }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "sku": { "type": "string" }, "unitPrice": { "type": "number", "format": "double", "example": 5.99 } } }, "QuoteResponse": { "type": "object", "description": "A binding price. Pass `quoteId` to `POST /orders` before `expiresAt`.", "required": [ "quoteId", "status", "postalCode", "lines", "subtotal", "shipping", "tax", "total", "currency", "estimatedDeliveryDays", "expiresAt", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string", "example": "USD" }, "estimatedDeliveryDays": { "type": "integer", "format": "int32", "example": 2, "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteLineResponse" } }, "postalCode": { "type": "string" }, "quoteId": { "type": "string" }, "shipping": { "type": "number", "format": "double", "example": 2.99 }, "status": { "type": "string", "description": "`OPEN`, `ACCEPTED` or `EXPIRED`." }, "subtotal": { "type": "number", "format": "double", "example": 5.99 }, "tax": { "type": "number", "format": "double" }, "total": { "type": "number", "format": "double", "example": 8.98 } } }, "ResolveIntentRequest": { "type": "object", "required": [ "intent" ], "properties": { "intent": { "type": "string", "description": "What the user needs, in plain language.", "example": "replace remote batteries" }, "limit": { "type": [ "integer", "null" ], "description": "Maximum candidates in `matches` (1-20, default 5).", "minimum": 0 } } }, "ResolveIntentResponse": { "type": "object", "required": [ "recommended_products", "matches" ], "properties": { "matches": { "type": "array", "items": { "$ref": "#/components/schemas/IntentMatchResponse" } }, "recommended_products": { "type": "array", "items": { "type": "string" }, "description": "SKUs to buy for this intent, best first. Empty when nothing in the catalog fits.", "example": [ "AA_BATTERY_STANDARD_4" ] } } }, "ShippingAddressRequest": { "type": "object", "description": "US delivery address.", "required": [ "recipient", "line1", "city", "region", "postalCode", "country" ], "properties": { "city": { "type": "string" }, "country": { "type": "string", "description": "`US`." }, "line1": { "type": "string" }, "line2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string", "description": "5-digit ZIP, or ZIP+4." }, "recipient": { "type": "string" }, "region": { "type": "string", "description": "Two-letter US state code." } }, "additionalProperties": false }, "SkuStat": { "type": "object", "required": [ "sku", "units", "lines" ], "properties": { "lines": { "type": "integer", "format": "int64", "minimum": 0 }, "sku": { "type": "string" }, "units": { "type": "integer", "format": "int64", "minimum": 0 } } }, "WaitlistEntry": { "type": "object", "description": "One waitlist signup (admin view).", "required": [ "email", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "email": { "type": "string", "example": "buyer@example.com" }, "invitedAt": { "type": [ "string", "null" ], "description": "Set once an invite key has been issued." }, "name": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } }, "WaitlistList": { "type": "object", "description": "Waitlist signups, newest first (admin view).", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WaitlistEntry" } } } }, "WaitlistRequest": { "type": "object", "description": "Ask for a private-beta invite key.", "required": [ "email" ], "properties": { "email": { "type": "string", "description": "Where the invite key should be sent.", "example": "buyer@example.com" }, "name": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ], "description": "What you want to use the API for.", "example": "Office restocking agent for a 40-person company" } } }, "WaitlistResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Always `waitlisted`.", "example": "waitlisted" } } } }, "securitySchemes": { "admin_key": { "type": "http", "scheme": "bearer", "bearerFormat": "ao___" }, "invite_key": { "type": "http", "scheme": "bearer", "bearerFormat": "ao___" } } }, "tags": [ { "name": "catalog", "description": "Standardized SKUs, fixed prices, intent resolution" }, { "name": "purchasing", "description": "Binding quotes, orders and agent-to-agent payment" }, { "name": "access", "description": "Private beta waitlist and invite keys" }, { "name": "analytics", "description": "Business metrics (operators only)" }, { "name": "system", "description": "Health" } ] }