{"openapi":"3.1.0","info":{"title":"PIG by Harvie API","version":"1.1.0","description":"Order groceries from Harvie's independent food network with human approval required for every payment. This is the normative REST interface. Catalog and fulfillment authority remain in PIG Operations. Agents cannot pay, refund, cancel, message, or mutate inventory."},"servers":[{"url":"https://www.pigoffers.com"}],"externalDocs":{"url":"https://www.pigoffers.com/agents"},"tags":[{"name":"Discovery"},{"name":"Enrollment"},{"name":"Catalog"},{"name":"Cart"},{"name":"Checkout"},{"name":"Orders"}],"paths":{"/api/agent/v1":{"get":{"operationId":"getAgentDiscovery","tags":["Discovery"],"security":[],"parameters":[{"$ref":"#/components/parameters/CorrelationId"}],"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Discovery"}}}}}}}}},"/api/agent/v1/device/authorizations":{"post":{"operationId":"createDeviceAuthorization","tags":["Enrollment"],"summary":"Create a short-lived pending device request. This creates no product, hold, Stripe, or order effect.","security":[],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceAuthorizationRequest"}}}},"responses":{"201":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DeviceAuthorization"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/device/token":{"post":{"operationId":"exchangeDeviceAuthorization","tags":["Enrollment"],"security":[],"parameters":[{"$ref":"#/components/parameters/CorrelationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["device_code"],"properties":{"device_code":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"}}}}}},"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TokenResponse"}}}}}},"202":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","required":["state","interval"],"properties":{"state":{"const":"authorization_pending"},"interval":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/catalog/products":{"get":{"operationId":"searchProducts","tags":["Catalog"],"security":[{"AgentBearer":["catalog:read"]}],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"department","in":"query","schema":{"type":"string","maxLength":120}},{"name":"category","in":"query","schema":{"type":"string","maxLength":120}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":500}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CatalogSearchResult"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/catalog/products/{productId}":{"get":{"operationId":"getProduct","tags":["Catalog"],"security":[{"AgentBearer":["catalog:read"]}],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"name":"productId","in":"path","required":true,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"404":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/cart/preview":{"post":{"operationId":"previewCart","tags":["Cart"],"summary":"Create a non-reserving quote. No inventory or delivery capacity is held.","security":[{"AgentBearer":["cart:quote"]}],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lines","gratuity"],"properties":{"lines":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["productId","variantId","quantity"],"properties":{"productId":{"type":"string","minLength":1,"maxLength":200},"variantId":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":100}}}},"delivery_address":{"type":"object","additionalProperties":false,"required":["line1","city","state","postal_code"],"properties":{"line1":{"type":"string","minLength":1,"maxLength":500},"line2":{"type":["string","null"],"maxLength":500},"city":{"type":"string","minLength":1,"maxLength":200},"state":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postal_code":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"country":{"type":"string","const":"US","default":"US"}}},"gratuity":{"oneOf":[{"type":"object","additionalProperties":false,"required":["kind","origin"],"properties":{"kind":{"const":"none"},"origin":{"const":"explicit"}}},{"type":"object","additionalProperties":false,"required":["kind","origin","percentageBps"],"properties":{"kind":{"const":"percentage"},"origin":{"const":"explicit"},"percentageBps":{"type":"integer","minimum":0,"maximum":4000}}},{"type":"object","additionalProperties":false,"required":["kind","origin","amountCents"],"properties":{"kind":{"const":"fixed"},"origin":{"const":"explicit"},"amountCents":{"type":"integer","minimum":0,"maximum":10000}}}]}}}}}},"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CartPreview"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/checkout/prepare":{"post":{"operationId":"prepareCheckout","tags":["Checkout"],"summary":"Create or reconcile one exact hold, order shell, and Stripe Checkout. The agent cannot complete payment.","security":[{"AgentBearer":["checkout:create"]}],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["preview_token"],"properties":{"preview_token":{"type":"string","minLength":1,"maxLength":12000,"description":"Opaque signed cart preview returned by pig_cart_preview."}}}}}},"responses":{"201":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PreparedCheckout"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}},"/api/agent/v1/orders/{orderId}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Read only this connection's own immutable order and its separate provider stages.","security":[{"AgentBearer":["order:read:self"]}],"parameters":[{"$ref":"#/components/parameters/CorrelationId"},{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OrderReadback"}}}}}},"400":{"$ref":"#/components/responses/AgentError"},"401":{"$ref":"#/components/responses/AgentError"},"403":{"$ref":"#/components/responses/AgentError"},"404":{"$ref":"#/components/responses/AgentError"},"409":{"$ref":"#/components/responses/AgentError"},"429":{"$ref":"#/components/responses/AgentError"},"500":{"$ref":"#/components/responses/AgentError"},"503":{"$ref":"#/components/responses/AgentError"}}}}},"components":{"securitySchemes":{"AgentBearer":{"type":"oauth2","description":"A revocable PIG agent connection. Device credentials and MCP OAuth resolve to the same AgentPrincipal.","flows":{"authorizationCode":{"authorizationUrl":"https://www.pigoffers.com/oauth/authorize","tokenUrl":"https://www.pigoffers.com/oauth/token","refreshUrl":"https://www.pigoffers.com/oauth/token","scopes":{"catalog:read":"catalog:read","cart:quote":"cart:quote","checkout:create":"checkout:create","order:read:self":"order:read:self"}}}}},"parameters":{"CorrelationId":{"name":"X-Correlation-Id","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Optional safe caller correlation identity. PIG returns the accepted value or a generated UUID."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16,"maxLength":200,"pattern":"^[A-Za-z0-9._:-]+$","description":"Caller-generated stable identity. Exact replays return the original result; reuse with a different payload is rejected."}}},"responses":{"AgentError":{"description":"Stable safe error envelope","headers":{"X-Correlation-Id":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","retryable","correlation_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"correlation_id":{"type":"string"},"resource_id":{"type":["string","null"]},"reconciliation":{"type":["string","null"]}}}}}}}}},"schemas":{"Discovery":{"type":"object","additionalProperties":true,"required":["name","short_name","description","version","enabled","checkout_enabled","inventory_interface","human_docs_url","openapi_url","mcp_url","install_options","authorization","payment"],"properties":{"name":{"const":"PIG by Harvie"},"short_name":{"const":"PIG"},"description":{"const":"Order groceries from Harvie's independent food network with human approval required for every payment."},"version":{"const":"v1"},"enabled":{"type":"boolean"},"checkout_enabled":{"type":"boolean"},"inventory_interface":{"const":"pig_ops"},"human_docs_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"},"install_options":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["provider","mode","setup_url"],"properties":{"provider":{"enum":["openai","anthropic","xai","generic_mcp","openapi"]},"mode":{"enum":["directory","custom","api","openapi"]},"setup_url":{"type":"string","format":"uri"}}}},"authorization":{"type":"object","required":["rest","mcp"],"properties":{"rest":{"const":"device_authorization"},"mcp":{"const":"oauth_2_1_pkce"}}},"payment":{"type":"object","required":["provider","human_approval_required","agent_can_complete_payment"],"properties":{"provider":{"const":"stripe_link"},"human_approval_required":{"const":true},"agent_can_complete_payment":{"const":false}}}}},"DeviceAuthorizationRequest":{"type":"object","additionalProperties":false,"required":["client_name"],"properties":{"client_name":{"type":"string","minLength":1,"maxLength":80},"public_client_id":{"type":["string","null"],"maxLength":200},"scopes":{"type":"array","minItems":1,"maxItems":4,"uniqueItems":true,"items":{"enum":["catalog:read","cart:quote","checkout:create","order:read:self"]}}}},"DeviceAuthorization":{"type":"object","additionalProperties":false,"required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval","scopes"],"properties":{"device_code":{"type":"string","writeOnly":true},"user_code":{"type":"string","writeOnly":true},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer"},"interval":{"type":"integer"},"scopes":{"type":"array","items":{"enum":["catalog:read","cart:quote","checkout:create","order:read:self"]}}}},"TokenResponse":{"type":"object","additionalProperties":false,"required":["state","access_token","token_type","expires_in","connection_id","scopes"],"properties":{"state":{"const":"approved"},"access_token":{"type":"string","writeOnly":true},"token_type":{"const":"Bearer"},"expires_in":{"type":"integer"},"connection_id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"enum":["catalog:read","cart:quote","checkout:create","order:read:self"]}}}},"Product":{"type":"object","additionalProperties":true,"required":["product_id","name","variants"],"properties":{"product_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"producer":{"type":["string","null"]},"variants":{"type":"array","items":{"type":"object","additionalProperties":true,"required":["canonical_sku_id","price","availability"],"properties":{"canonical_sku_id":{"type":"string"},"price":{"type":"object","additionalProperties":true},"availability":{"type":"object","additionalProperties":true}}}}}},"CatalogSearchResult":{"type":"object","additionalProperties":false,"required":["products","authority"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"next_cursor":{"type":["string","null"]},"projection":{"type":["object","null"],"additionalProperties":true},"authority":{"const":"pig_ops"}}},"CartPreview":{"type":"object","additionalProperties":true,"required":["preview_token","expires_at","state","authority","fulfillment","lines","amounts","checkout_ready"],"properties":{"preview_token":{"type":"string","writeOnly":true},"expires_at":{"type":"string","format":"date-time"},"state":{"const":"quoted"},"authority":{"const":"pig_ops"},"fulfillment":{"type":"object","additionalProperties":true,"description":"Eastern-time service date/window plus UTC instants where available."},"lines":{"type":"array","items":{"type":"object","additionalProperties":true}},"amounts":{"type":"object","additionalProperties":true,"required":["currency"],"properties":{"currency":{"type":"string","enum":["USD"]},"merchandise_gross_cents":{"type":["integer","null"]},"discount_cents":{"type":["integer","null"]},"merchandise_final_cents":{"type":["integer","null"]},"delivery_fee_cents":{"type":["integer","null"]},"tip_cents":{"type":["integer","null"]},"tax_cents":{"type":["integer","null"]},"final_payable_total_cents":{"type":["integer","null"]}}},"checkout_ready":{"type":"boolean"}}},"PreparedCheckout":{"type":"object","additionalProperties":true,"required":["checkout_attempt_id","order_id","checkout_url","state","amounts","line_items","link"],"properties":{"checkout_attempt_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"checkout_url":{"type":"string","format":"uri","writeOnly":true},"stripe_checkout_session_id":{"type":"string","writeOnly":true},"state":{"const":"awaiting_human_approval"},"expires_at":{"type":["string","null"],"format":"date-time"},"amounts":{"type":"object","additionalProperties":true},"line_items":{"type":"array","items":{"type":"object","additionalProperties":true}},"reservation":{"type":["object","null"],"additionalProperties":true},"link":{"type":"object","additionalProperties":false,"required":["merchant_name","approval_ready","agent_can_complete_payment","required_action"],"properties":{"merchant_name":{"const":"PIG Supply"},"approval_ready":{"type":"boolean"},"agent_can_complete_payment":{"const":false},"required_action":{"type":"string"}}}}},"OrderReadback":{"type":"object","additionalProperties":false,"required":["order","items","checkout_attempts","operations"],"properties":{"order":{"type":"object","additionalProperties":true,"description":"Payment, allocation, fulfillment, and delivery states remain separate."},"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"checkout_attempts":{"type":"array","items":{"type":"object","additionalProperties":true}},"operations":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}