{ "openapi": "3.1.0", "info": { "title": "SAAVI Insights API", "version": "1.0.0", "description": "Read-only KPI, order-history and export API over SAAVI data. Each SAAVI customer is an isolated organisation; a key only ever sees its own organisation's data. Reads are served from an hourly Postgres mirror, never from the customer's live SAAVI database." }, "servers": [ { "url": "https://insights.saavi.com.au", "description": "Production (canonical)" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Meta": { "type": "object", "required": [ "correlation_id", "timestamp", "version" ], "properties": { "correlation_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "version": { "type": "string" }, "data_as_of": { "type": [ "string", "null" ], "format": "date-time" }, "freshness_seconds": { "type": [ "integer", "null" ] }, "data_quality": { "type": "string", "enum": [ "live", "synthetic" ] } } } } }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/public/v1/health": { "get": { "summary": "Liveness plus data freshness for the presented key.", "description": "Required scope: none", "security": [], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/organization": { "get": { "summary": "Reporting rules in force: GST basis, week start, cancelled-order handling, pallet basis.", "description": "Required scope: metrics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/metrics/summary": { "get": { "summary": "Sales value, order count, pallets, average order value and unique customers, with prior-period comparison and the bucket series.", "description": "Required scope: metrics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Bucket size. Defaults to day.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start (YYYY-MM-DD). Defaults to a period-appropriate look-back.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end (YYYY-MM-DD). Defaults to today.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/metrics/top-customers": { "get": { "summary": "Customers ranked by sales value across the window, with share of window sales.", "description": "Required scope: metrics:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Defaults to month.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Inclusive start.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "How many customers. Defaults to 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/orders": { "get": { "summary": "Paginated order history.", "description": "Required scope: orders:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive start. Defaults to 30 days ago.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size. Defaults to 50.", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip. Defaults to 0.", "schema": { "type": "integer" } }, { "name": "customer_code", "in": "query", "required": false, "description": "Restrict to one customer code.", "schema": { "type": "string" } }, { "name": "include_cancelled", "in": "query", "required": false, "description": "Include cancelled orders.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/orders/{orderId}": { "get": { "summary": "One order with its lines.", "description": "Required scope: orders:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "SAAVI cart id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/exports/orders.csv": { "get": { "summary": "CSV export of order history for spreadsheet or ETL consumers.", "description": "Required scope: exports:read", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Inclusive start.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Inclusive end.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Row cap. Defaults to 5000.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/webhooks": { "get": { "summary": "List webhook subscriptions.", "description": "Required scope: webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } }, "post": { "summary": "Create a webhook subscription. The signing secret is returned once.", "description": "Required scope: webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } }, "delete": { "summary": "Deactivate a webhook subscription.", "description": "Required scope: webhooks:manage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/api/public/v1/bridge/ingest": { "get": { "summary": "Sync watermarks and last run status, for the on-prem bridge runner.", "description": "Required scope: bridge:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } }, "post": { "summary": "Push a batch of SAAVI rows into the mirror; the final batch recomputes rollups and fires webhooks.", "description": "Required scope: bridge:write", "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Success envelope." }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Key lacks the required scope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } } }, "x-scopes": [ "metrics:read", "orders:read", "exports:read", "webhooks:manage", "bridge:write" ], "x-webhook-events": [ "metrics.rollup.completed", "orders.ingested", "sync.failed" ], "x-rate-limit": "Per-key, per-minute. Limit, remaining and reset are returned in X-RateLimit-* response headers." }