{ "openapi": "3.1.0", "info": { "title": "Quantus Pulse — Aurelia Partner API", "version": "1.0.0", "description": "Keyed, scoped, throttled REST surface for partner platforms. Auth: `x-api-key: qp_live_…` (or `Authorization: Bearer qp_live_…`). Write calls accept an `idempotency-key` header. Webhooks are signed HMAC-SHA256 over `${timestamp}.${rawBody}` in the `x-quantus-signature` header (`t=…,v1=…`).\n\n**Pagination.** `/clients`, `/mandates`, `/deals` and `/webhooks/{id}/deliveries` are cursor-paginated: pass `limit` (1–100, default 25) and the `next_cursor` from the previous page as `cursor`; `has_more` tells you when to stop.\n\n**Error codes.** `missing_api_key`, `invalid_api_key`, `expired_api_key` (401); `not_a_partner_key`, `insufficient_scope` (403); `invalid_request` (400); `not_found`, `unknown_route`, `unknown_version` (404); `mandate_not_approved` (409, webhook replay of a mandate not approved for release); `rate_limited` (429); `read_failed`, `write_failed`, `auth_unavailable`, `internal_error` (500).", "contact": { "name": "Quantus Pulse Desk", "url": "https://quantuspulse.com/contact" } }, "servers": [ { "url": "https://eqxgnxgbvvrjaxjiznjo.supabase.co/functions/v1/aurelia-api/v1" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Health" }, { "name": "Clients" }, { "name": "Mandates" }, { "name": "Deals" }, { "name": "Introductions" }, { "name": "Webhooks" } ], "paths": { "/ping": { "get": { "tags": [ "Health" ], "summary": "Key introspection", "operationId": "ping", "responses": { "200": { "description": "Key is valid", "content": { "application/json": { "example": { "ok": true, "partner": "aurelia", "scopes": [ "mandates:read", "mandates:write", "deals:read", "clients:write", "webhooks:write" ], "version": "v1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients": { "post": { "tags": [ "Clients" ], "summary": "Create or upsert a partner client", "operationId": "createClient", "description": "Idempotent on (partner, external_ref). Requires scope `clients:write`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" }, "example": { "display_name": "Client A-217", "external_ref": "aurelia-217", "region": "UAE", "note": "Aviation + longevity mandates", "metadata": { "tier": "prime" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "client": { "id": "e1f9…", "display_name": "Client A-217", "external_ref": "aurelia-217", "region": "UAE", "status": "active", "created_at": "2026-08-19T21:04:11.221Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Clients" ], "summary": "List partner clients", "operationId": "listClients", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "clients": [], "has_more": false, "next_cursor": null } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Cursor-paginated: response carries `has_more` and `next_cursor`." } }, "/mandates": { "post": { "tags": [ "Mandates" ], "summary": "Submit a mandate", "operationId": "createMandate", "description": "Idempotent on (partner, external_ref). Requires scope `mandates:write`. Emits `mandate.created`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateInput" }, "example": { "vertical": "aviation", "brief": "Global 8000 or equivalent ULR airframe, sub-4000ft field performance, discreet off-market only.", "external_ref": "aurelia-mandate-901", "client_id": null, "budget_min_cents": 4000000000, "budget_max_cents": 6000000000, "currency": "GBP", "timeline_days": 90, "location": "Dubai", "metadata": { "priority": "high" } } } } }, "responses": { "201": { "description": "Received", "content": { "application/json": { "example": { "mandate": { "id": "9c3b…", "external_ref": "aurelia-mandate-901", "vertical": "aviation", "status": "received", "created_at": "2026-08-19T21:06:02.114Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Mandates" ], "summary": "List mandates", "operationId": "listMandates", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/MandateStatus" } }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "mandates": [ { "id": "9c3b…", "external_ref": "aurelia-mandate-901", "vertical": "aviation", "status": "sourcing", "matched_deal_id": null, "created_at": "2026-08-19T21:06:02.114Z", "updated_at": "2026-08-19T22:00:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Cursor-paginated: response carries `has_more` and `next_cursor`." } }, "/mandates/{id}": { "get": { "tags": [ "Mandates" ], "summary": "Retrieve a mandate with any matched intercept", "operationId": "getMandate", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "mandate": { "id": "9c3b…", "status": "matched", "vertical": "aviation", "matched_deal_id": "77aa…" }, "matched_deal": { "id": "77aa…", "deal_number": "QP-1042", "title": "ULR airframe — private allocation", "category": "aviation", "quantus_score": 88, "confidence_level": "high", "status": "active", "created_at": "2026-08-10T09:00:00.000Z" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/mandates/{id}/cancel": { "post": { "tags": [ "Mandates" ], "summary": "Cancel a mandate", "operationId": "cancelMandate", "description": "Requires scope `mandates:write`. Emits `mandate.status_changed`.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "example": { "mandate": { "id": "9c3b…", "status": "cancelled" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deals": { "get": { "tags": [ "Deals" ], "summary": "List curated intercepts", "operationId": "listDeals", "description": "Requires scope `deals:read`. Returns curated, partner-visible intercepts only. Cursor-paginated: response carries `has_more` and `next_cursor`.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "example": "aviation" }, { "name": "min_score", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "example": 80 }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "has_more": { "type": "boolean", "description": "True when another page exists." }, "next_cursor": { "type": [ "string", "null" ], "format": "date-time", "description": "Pass back as `cursor` to fetch the next page." } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deals/{id}": { "get": { "tags": [ "Deals" ], "summary": "Retrieve a curated intercept", "operationId": "getDeal", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deal": { "$ref": "#/components/schemas/Deal" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/introductions": { "post": { "tags": [ "Introductions" ], "summary": "Refer a private introduction", "operationId": "createIntroduction", "description": "Requires scope `clients:write`. Emits `introduction.received`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntroductionInput" }, "example": { "name": "H. Marchetti", "private_email": "office@example.com", "region": "Monaco", "note": "Marine + sovereignty interest" } } } }, "responses": { "201": { "description": "Received", "content": { "application/json": { "example": { "introduction": { "id": "2b71…", "status": "new", "created_at": "2026-08-19T21:12:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" } } } }, "/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint", "operationId": "createWebhook", "description": "Requires scope `webhooks:write`. The `secret` is returned exactly once — store it immediately.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "example": { "url": "https://aurelia.example.com/hooks/quantus", "events": [ "mandate.created", "mandate.status_changed", "deal.matched", "introduction.received" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "webhook": { "id": "aa10…", "url": "https://aurelia.example.com/hooks/quantus", "events": [ "mandate.created" ], "is_active": true, "created_at": "2026-08-19T21:15:00.000Z" }, "secret": "whsec_…", "signature_scheme": "HMAC-SHA256 over `${timestamp}.${body}`, header x-quantus-signature" } } } } } }, "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "operationId": "listWebhooks", "description": "Cursor-paginated. Pass `next_cursor` from the previous response as `cursor` until `has_more` is false.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "webhooks": [], "has_more": false, "next_cursor": null } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Deactivate a webhook endpoint", "operationId": "deleteWebhook", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "example": { "deleted": true, "id": "aa10…" } } } } } } }, "/mandates/{id}/events": { "get": { "tags": [ "Mandates" ], "summary": "Mandate timeline", "operationId": "listMandateEvents", "description": "Requires scope `mandates:read`. Oldest-first, capped at 200 events — not cursor-paginated.", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "mandate_id": "9c3b…", "events": [ { "id": "e1", "kind": "received", "status": "received", "note": "Mandate received on the partner API.", "actor": "system", "created_at": "2026-08-19T10:00:02.000Z" }, { "id": "e2", "kind": "status_changed", "status": "sourcing", "note": "Sourcing engaged against the intercept ledger.", "actor": "system", "created_at": "2026-08-19T10:00:04.000Z" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mandates/{id}/notes": { "get": { "tags": [ "Mandates" ], "summary": "List desk and partner notes", "operationId": "listMandateNotes", "description": "Requires scope `mandates:read`. Oldest-first, capped at 200 notes — not cursor-paginated.", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "mandate_id": "9c3b…", "notes": [ { "id": "n1", "author": "desk", "body": "Holder wants proof of funds before viewing.", "metadata": {}, "created_at": "2026-08-19T12:10:00.000Z" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Mandates" ], "summary": "Add a partner note to a mandate", "operationId": "createMandateNote", "description": "Requires scope `mandates:write`. Appends a `note_added` entry to the mandate timeline.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 2, "maxLength": 4000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "example": { "body": "Principal can close in 21 days, cash." } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "note": { "id": "n2", "author": "partner", "body": "Principal can close in 21 days, cash.", "created_at": "2026-08-19T12:31:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mandates/{id}/share": { "post": { "tags": [ "Mandates" ], "summary": "Mint a client-facing progress link", "operationId": "createMandateShare", "description": "Requires scope `mandates:write`. Returns an expiring, login-free URL showing sanitised progress only — no vendor identities.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_in_hours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 72 } } }, "example": { "expires_in_hours": 72 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "share": { "id": "s1", "expires_at": "2026-08-22T12:31:00.000Z", "created_at": "2026-08-19T12:31:00.000Z" }, "url": "https://quantuspulse.com/mandate/shr_…", "note": "Sanitised progress only — no vendor identities, no login required." } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Inspect webhook deliveries", "operationId": "listWebhookDeliveries", "description": "Requires scope `webhooks:read`. Newest-first and cursor-paginated: response carries `has_more` and `next_cursor`.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "deliveries": [ { "id": "d1", "event": "deal.matched", "delivery_status": "retrying", "response_status": 502, "attempt_count": 2, "next_attempt_at": "2026-08-19T12:05:00.000Z", "last_attempt_at": "2026-08-19T11:55:00.000Z", "duration_ms": 812, "error": "Bad gateway", "created_at": "2026-08-19T11:50:00.000Z" } ], "has_more": false, "next_cursor": null } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/{id}/deliveries/{delivery_id}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a delivery", "operationId": "replayWebhookDelivery", "description": "Requires scope `webhooks:write`. Re-sends the stored payload with a fresh signature and records a new delivery row (`is_replay: true`, `replay_of_id` pointing at the original), so replays are always visible in the inspector.", "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/DeliveryId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Replay sent and logged", "content": { "application/json": { "example": { "replayed": true, "delivery_id": "d1", "replay_delivery_id": "d9", "response_status": 200, "error": null } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The mandate behind this delivery is not operator-approved for release, so nothing was sent.", "content": { "application/json": { "example": { "error": { "code": "mandate_not_approved", "message": "This delivery belongs to a mandate that is not approved for release." } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "webhooks": { "quantusEvent": { "post": { "summary": "Quantus → partner event delivery", "description": "Verify `x-quantus-signature: t=,v1=` as HMAC-SHA256 of `${t}.${rawBody}` using your webhook secret. Reject timestamps older than 300s.", "requestBody": { "content": { "application/json": { "example": { "event": "mandate.status_changed", "created_at": "2026-08-19T22:00:00.000Z", "data": { "mandate": { "id": "9c3b…", "status": "matched" } } } } } }, "responses": { "200": { "description": "Acknowledged" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Partner key, e.g. qp_live_…" } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "IdempotencyKey": { "name": "idempotency-key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Stable key so retried writes are never duplicated." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Opaque cursor: pass the `next_cursor` from the previous page. Pages are ordered newest-first by `created_at`." }, "DeliveryId": { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "Unauthorized": { "description": "Missing, malformed, revoked or expired key", "content": { "application/json": { "example": { "error": { "code": "invalid_api_key", "message": "Key not recognised or revoked." } } } } }, "Forbidden": { "description": "Key lacks the required scope", "content": { "application/json": { "example": { "error": { "code": "insufficient_scope", "message": "Key is missing the \"mandates:write\" scope." } } } } }, "NotFound": { "description": "Resource not visible to this key", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Mandate not found." } } } } }, "ValidationError": { "description": "Schema validation failed", "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "Validation failed", "fields": { "brief": [ "String must contain at least 20 character(s)" ] } } } } } }, "RateLimited": { "description": "Per-minute quota exceeded; honour Retry-After", "headers": { "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Too many requests." } } } } }, "ServerError": { "description": "Ledger or credential-store failure (`read_failed`, `write_failed`, `auth_unavailable`, `internal_error`)", "content": { "application/json": { "example": { "error": { "code": "write_failed", "message": "The write was rejected by the ledger." } } } } } }, "schemas": { "Vertical": { "type": "string", "enum": [ "real_estate", "aviation", "marine", "art_antiquities", "hard_assets", "sovereignty", "longevity", "security", "sovereign_finance", "jewelry", "automotive", "natural_resources", "hospitality", "space", "business_acquisition", "philanthropy", "private_equity", "asset_acquisition", "other" ] }, "MandateStatus": { "type": "string", "enum": [ "received", "triaging", "sourcing", "matched", "closed", "cancelled", "rejected" ] }, "MandateInput": { "type": "object", "required": [ "vertical", "brief" ], "properties": { "vertical": { "$ref": "#/components/schemas/Vertical" }, "brief": { "type": "string", "minLength": 20, "maxLength": 4000 }, "external_ref": { "type": "string", "minLength": 1, "maxLength": 120 }, "client_id": { "type": "string", "format": "uuid" }, "budget_min_cents": { "type": "integer", "minimum": 0, "maximum": 2100000000 }, "budget_max_cents": { "type": "integer", "minimum": 0, "maximum": 2100000000 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "GBP" }, "timeline_days": { "type": "integer", "minimum": 0, "maximum": 3650 }, "location": { "type": "string", "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": true } } }, "ClientInput": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "external_ref": { "type": "string", "minLength": 1, "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 2000 }, "metadata": { "type": "object", "additionalProperties": true } } }, "IntroductionInput": { "type": "object", "required": [ "name", "private_email" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "private_email": { "type": "string", "format": "email", "maxLength": 320 }, "region": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 2000 } } }, "WebhookInput": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Must be https." }, "events": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string" }, "default": [ "mandate.created", "mandate.status_changed", "deal.matched", "introduction.received" ] } } }, "Deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deal_number": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "sub_category": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "valuation_range": { "type": [ "string", "null" ] }, "intelligence_summary": { "type": [ "string", "null" ] }, "quantus_score": { "type": [ "integer", "null" ] }, "confidence_level": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "lifecycle_state": { "type": [ "string", "null" ] }, "data_source": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Pagination": { "type": "object", "description": "Every list endpoint returns cursor pagination alongside its collection.", "properties": { "has_more": { "type": "boolean", "description": "True when another page exists." }, "next_cursor": { "type": [ "string", "null" ], "format": "date-time", "description": "Pass back as `cursor` to fetch the next page." } } } } } }