{ "openapi": "3.1.0", "info": { "title": "Meshi Partner API", "version": "0.1.0", "description": "Machine-readable v0 contract for the Meshi Partner API. The canonical base path is /api/v0/partner. The legacy /v0/partner alias is served during transition but is deprecated." }, "servers": [ { "url": "https://api.staging.meshi.io/api/v0/partner", "description": "Staging" }, { "url": "https://api.meshi.io/api/v0/partner", "description": "Production" } ], "security": [ { "PartnerBearerAuth": [] } ], "tags": [ { "name": "Service account" }, { "name": "ID resolution" }, { "name": "Events" }, { "name": "Sessions" }, { "name": "Attendees" }, { "name": "Runs" }, { "name": "Matches" }, { "name": "Review queue" } ], "paths": { "/auth": { "get": { "tags": [ "Service account" ], "operationId": "getPartnerAuth", "summary": "Probe the authenticated service-account key", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "responses": { "200": { "$ref": "#/components/responses/AuthResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/id-map/{kind}/{partner_id}": { "get": { "tags": [ "ID resolution" ], "operationId": "getPartnerIdMap", "summary": "Confirm that a partner-owned ID is mapped in this org", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/Kind" }, { "$ref": "#/components/parameters/PartnerId" } ], "responses": { "200": { "$ref": "#/components/responses/IdMapResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events": { "get": { "tags": [ "Events" ], "operationId": "listPartnerEvents", "summary": "List events for the authenticated org", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/EventListResponse" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Events" ], "operationId": "createPartnerEvent", "summary": "Create an event with a partner-owned event_id", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/EventResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}": { "get": { "tags": [ "Events" ], "operationId": "getPartnerEvent", "summary": "Read one event by partner-owned event_id", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "responses": { "200": { "$ref": "#/components/responses/EventResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/context": { "get": { "tags": [ "Events" ], "operationId": "getPartnerEventContext", "summary": "Read matchmaking context for an event", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "responses": { "200": { "$ref": "#/components/responses/EventContextResponse" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Events" ], "operationId": "updatePartnerEventContext", "summary": "Update matchmaking context for an event", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventContextRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/EventContextResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/review-queue": { "get": { "tags": [ "Review queue" ], "operationId": "listPartnerEventReviewQueue", "summary": "List open identity reviews for one event", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/ReviewQueueResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/sessions": { "get": { "tags": [ "Sessions" ], "operationId": "listPartnerSessions", "summary": "List sessions within an event", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/SessionListResponse" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Sessions" ], "operationId": "createPartnerSession", "summary": "Create a session within an event", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/SessionResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/sessions/{session_id}": { "get": { "tags": [ "Sessions" ], "operationId": "getPartnerSession", "summary": "Read one session by partner-owned session_id", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/SessionId" } ], "responses": { "200": { "$ref": "#/components/responses/SessionResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/attendees": { "get": { "tags": [ "Attendees" ], "operationId": "listPartnerAttendees", "summary": "List attendees within an event", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/AttendeeListResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/attendees/{attendee_id}/identity": { "get": { "tags": [ "Attendees" ], "operationId": "listPartnerAttendeeIdentityDecisions", "summary": "List identity decisions for one attendee", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/AttendeeId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/IdentityHistoryResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/attendees:import": { "put": { "tags": [ "Attendees", "Runs" ], "operationId": "importPartnerAttendees", "summary": "Import attendees into an event and enqueue an async import run", "description": "A single request may include at most 50,000 attendee rows. Larger rosters must be chunked into separate requests, each with its own idempotency_key.", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendeesImportRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/PartnerRunReplayResponse" }, "202": { "$ref": "#/components/responses/PartnerRunAcceptedResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/enrichment-runs": { "post": { "tags": [ "Runs" ], "operationId": "createPartnerEnrichmentRun", "summary": "Enqueue an async attendee enrichment run for an event", "description": "Returns a queued run. Poll GET /runs/{run_id} until the run reaches succeeded, partial, or failed.", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCreateForEventRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/PartnerRunReplayResponse" }, "202": { "$ref": "#/components/responses/PartnerRunAcceptedResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/match-runs": { "post": { "tags": [ "Runs", "Matches" ], "operationId": "createPartnerMatchRun", "summary": "Enqueue an async attendee match run for an event", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchRunCreateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/PartnerRunReplayResponse" }, "202": { "$ref": "#/components/responses/PartnerRunAcceptedResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/attendees/{attendee_id}/matches": { "get": { "tags": [ "Matches" ], "operationId": "listPartnerAttendeeMatches", "summary": "List top matches for one attendee", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/AttendeeId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/RunIdQuery" } ], "responses": { "200": { "$ref": "#/components/responses/AttendeeMatchListResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/matches": { "get": { "tags": [ "Matches" ], "operationId": "listPartnerEventMatches", "summary": "List matches across all attendee pairs for an event", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/RunIdQuery" }, { "$ref": "#/components/parameters/SessionIdQuery" }, { "$ref": "#/components/parameters/GoalQuery" } ], "responses": { "200": { "$ref": "#/components/responses/MatchListResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events/{event_id}/matches/{principal_partner_id}/{target_partner_id}": { "get": { "tags": [ "Matches" ], "operationId": "getPartnerPairMatch", "summary": "Read the match score for one ordered attendee pair", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/PrincipalPartnerId" }, { "$ref": "#/components/parameters/TargetPartnerId" }, { "$ref": "#/components/parameters/RunIdQuery" } ], "responses": { "200": { "$ref": "#/components/responses/PairMatchResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/runs": { "get": { "tags": [ "Runs" ], "operationId": "listPartnerRuns", "summary": "List partner runs for the authenticated org", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/RunKindQuery" } ], "responses": { "200": { "$ref": "#/components/responses/RunListResponse" }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Runs" ], "operationId": "createPartnerRun", "summary": "Create a generic partner run outside event scope", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericRunCreateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/PartnerRunReplayResponse" }, "201": { "$ref": "#/components/responses/PartnerRunCreatedResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/runs/{run_id}": { "get": { "tags": [ "Runs" ], "operationId": "getPartnerRun", "summary": "Poll one run to terminal status", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/RunId" } ], "responses": { "200": { "$ref": "#/components/responses/PartnerRunResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/review-queue": { "get": { "tags": [ "Review queue" ], "operationId": "listPartnerReviewQueue", "summary": "List all open identity reviews for the authenticated org", "x-required-scope": "partner:read", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "$ref": "#/components/responses/ReviewQueueResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/review-queue/{review_id}/resolve": { "post": { "tags": [ "Review queue" ], "operationId": "resolvePartnerReview", "summary": "Accept, reject, or mark distinct on an open identity review", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/ReviewId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveReviewRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/ResolveReviewResponse" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/review-queue/{review_id}/merge": { "post": { "tags": [ "Review queue" ], "operationId": "mergePartnerReview", "summary": "Resolve a review by merging one partner-mapped entity into another", "x-required-scope": "partner:write", "parameters": [ { "$ref": "#/components/parameters/CorrelationIdHeader" }, { "$ref": "#/components/parameters/ReviewId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeReviewRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/MergeReviewResponse" }, "default": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "PartnerBearerAuth": { "type": "http", "scheme": "bearer", "description": "Org-scoped Meshi service-account API key. Scope is method-gated: GET/HEAD/OPTIONS require partner:read or partner:write; POST/PUT require partner:write." } }, "parameters": { "CorrelationIdHeader": { "name": "x-correlation-id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional caller-supplied trace ID. Echoed in the x-correlation-id response header and response body." }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Page size. Invalid or out-of-range values are normalized by the server." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Cursor" }, "description": "Opaque next_cursor value from the previous page. Do not parse or construct it." }, "Kind": { "name": "kind", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerKind" } }, "PartnerId": { "name": "partner_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "EventId": { "name": "event_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "SessionId": { "name": "session_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "AttendeeId": { "name": "attendee_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "PrincipalPartnerId": { "name": "principal_partner_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "TargetPartnerId": { "name": "target_partner_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "RunId": { "name": "run_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "ReviewId": { "name": "review_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } }, "RunIdQuery": { "name": "run_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Uuid" } }, "SessionIdQuery": { "name": "session_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PartnerId" } }, "GoalQuery": { "name": "goal", "in": "query", "required": false, "schema": { "type": "string" } }, "RunKindQuery": { "name": "kind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/RunKind" } } }, "responses": { "Error": { "description": "Partner error envelope. All partner 4xx/5xx responses use this shape.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "AuthResponse": { "description": "Authenticated service-account details.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "IdMapResponse": { "description": "Partner ID is mapped.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdMapResponse" } } } }, "EventResponse": { "description": "Partner event.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "EventListResponse": { "description": "Paged partner events.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } }, "EventContextResponse": { "description": "Partner event context.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventContextResponse" } } } }, "SessionResponse": { "description": "Partner event session.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "SessionListResponse": { "description": "Paged partner event sessions.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } }, "AttendeeListResponse": { "description": "Paged partner event attendees.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendeeListResponse" } } } }, "IdentityHistoryResponse": { "description": "Paged attendee identity decision history.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityHistoryResponse" } } } }, "PartnerRunAcceptedResponse": { "description": "Async run accepted and queued.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRunWithReplay" } } } }, "PartnerRunCreatedResponse": { "description": "Run created.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRunWithReplay" } } } }, "PartnerRunReplayResponse": { "description": "Idempotent replay of an existing run.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRunWithReplay" } } } }, "PartnerRunResponse": { "description": "Partner run.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerRun" } } } }, "RunListResponse": { "description": "Paged partner runs.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } } }, "AttendeeMatchListResponse": { "description": "Paged matches for one attendee.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendeeMatchListResponse" } } } }, "MatchListResponse": { "description": "Paged matches for an event.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchListResponse" } } } }, "PairMatchResponse": { "description": "One pair match.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "event_id" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" } } }, { "$ref": "#/components/schemas/MatchObject" }, { "$ref": "#/components/schemas/CorrelationBody" } ] } } } }, "ReviewQueueResponse": { "description": "Paged open identity reviews.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewQueueResponse" } } } }, "ResolveReviewResponse": { "description": "Review resolved.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveReviewResponse" } } } }, "MergeReviewResponse": { "description": "Review resolved by merge.", "headers": { "x-correlation-id": { "$ref": "#/components/headers/CorrelationId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeReviewResponse" } } } } }, "headers": { "CorrelationId": { "description": "Effective correlation ID for this request.", "schema": { "type": "string" } } }, "schemas": { "PartnerId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "minLength": 1, "maxLength": 128 }, "PartnerKind": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,63}$", "minLength": 1, "maxLength": 64 }, "Uuid": { "type": "string", "format": "uuid" }, "IsoTimestamp": { "type": "string", "format": "date-time" }, "Cursor": { "type": [ "string", "null" ], "description": "Opaque pagination cursor. Pass it back verbatim as cursor." }, "JsonObject": { "type": "object", "additionalProperties": true }, "CorrelationBody": { "type": "object", "required": [ "correlation_id" ], "properties": { "correlation_id": { "type": "string" } } }, "ErrorEnvelope": { "type": "object", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable detail. Do not parse for control flow." }, "correlation_id": { "type": "string" } }, "additionalProperties": false }, "AuthResponse": { "allOf": [ { "type": "object", "required": [ "org_id", "principal_type", "service_account_user_id", "scopes" ], "properties": { "org_id": { "type": "string" }, "principal_type": { "type": "string", "const": "service_account" }, "service_account_user_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "partner:read", "partner:write" ] } } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "IdMapResponse": { "allOf": [ { "type": "object", "required": [ "kind", "partner_id", "mapped" ], "properties": { "kind": { "$ref": "#/components/schemas/PartnerKind" }, "partner_id": { "$ref": "#/components/schemas/PartnerId" }, "mapped": { "type": "boolean", "const": true } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "EventCreateRequest": { "type": "object", "required": [ "event_id", "title" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ], "maxLength": 128 }, "visibility": { "type": [ "string", "null" ], "maxLength": 32 }, "url_slug": { "type": [ "string", "null" ], "maxLength": 128 } } }, "EventObject": { "type": "object", "required": [ "event_id", "title", "description", "event_details", "objectives", "welcome_instructions", "start_date", "end_date", "timezone", "visibility", "url_slug", "created_at", "updated_at" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "event_details": { "type": [ "string", "null" ] }, "objectives": { "type": [ "string", "null" ] }, "welcome_instructions": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ] }, "url_slug": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/IsoTimestamp" }, "updated_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "EventResponse": { "allOf": [ { "$ref": "#/components/schemas/EventObject" }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "EventListResponse": { "allOf": [ { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EventObject" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "EventContextRequest": { "type": "object", "properties": { "event_details": { "type": "string", "maxLength": 4000 }, "objectives": { "type": "string", "maxLength": 4000 }, "welcome_instructions": { "type": "string", "maxLength": 4000 } }, "minProperties": 1 }, "EventContextResponse": { "allOf": [ { "type": "object", "required": [ "event_id", "context" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "context": { "type": "object", "required": [ "event_details", "objectives", "welcome_instructions" ], "properties": { "event_details": { "type": [ "string", "null" ] }, "objectives": { "type": [ "string", "null" ] }, "welcome_instructions": { "type": [ "string", "null" ] } } } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "SessionCreateRequest": { "type": "object", "required": [ "session_id", "title", "start_timestamp" ], "properties": { "session_id": { "$ref": "#/components/schemas/PartnerId" }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "start_timestamp": { "$ref": "#/components/schemas/IsoTimestamp" }, "end_timestamp": { "type": [ "string", "null" ], "format": "date-time" } } }, "SessionObject": { "type": "object", "required": [ "session_id", "event_id", "title", "description", "start_timestamp", "end_timestamp", "metadata", "created_at" ], "properties": { "session_id": { "$ref": "#/components/schemas/PartnerId" }, "event_id": { "$ref": "#/components/schemas/PartnerId" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "start_timestamp": { "$ref": "#/components/schemas/IsoTimestamp" }, "end_timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/JsonObject" }, "created_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "SessionResponse": { "allOf": [ { "$ref": "#/components/schemas/SessionObject" }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "SessionListResponse": { "allOf": [ { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SessionObject" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "AttendeeObject": { "type": "object", "required": [ "attendee_id", "event_id", "display_name", "title", "company", "event", "identity" ], "properties": { "attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "event_id": { "$ref": "#/components/schemas/PartnerId" }, "display_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "event": { "type": "object", "properties": { "role_at_event": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ] }, "goal": { "type": [ "string", "null" ] }, "needs": { "type": [ "array", "null" ], "items": { "type": "string" } }, "offers": { "type": [ "array", "null" ], "items": { "type": "string" } }, "onboarded_at": { "type": [ "string", "null" ], "format": "date-time" }, "joined_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "identity": { "type": "object", "required": [ "review_required", "open_review_count" ], "properties": { "review_required": { "type": "boolean" }, "open_review_count": { "type": "integer", "minimum": 0 } } } } }, "AttendeeListResponse": { "allOf": [ { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AttendeeObject" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "IdentityDecision": { "type": "object", "required": [ "decision_id", "source_path", "candidate_ref", "decision", "confidence", "reasoning", "evaluator", "created_at" ], "properties": { "decision_id": { "$ref": "#/components/schemas/Uuid" }, "source_path": { "type": "string" }, "candidate_ref": { "type": [ "string", "null" ] }, "decision": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "reasoning": { "type": [ "string", "null" ] }, "evaluator": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "IdentityHistoryResponse": { "allOf": [ { "type": "object", "required": [ "event_id", "attendee_id", "items", "next_cursor" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/IdentityDecision" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "WebhookUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Accepted, stored, and echoed back, but v0 webhooks are not delivered. Integrations must poll GET /runs/{run_id} for terminal status." }, "IdempotencyKey": { "type": "string", "minLength": 1, "maxLength": 256 }, "AttendeeImportRow": { "type": "object", "required": [ "attendee_id", "name" ], "properties": { "attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "name": { "type": "string", "maxLength": 240 }, "email": { "type": "string", "maxLength": 320 }, "linkedin_url": { "type": "string", "maxLength": 2048 }, "title": { "type": "string", "maxLength": 512 }, "company": { "type": "string", "maxLength": 512 }, "raw_data": { "$ref": "#/components/schemas/JsonObject" } } }, "AttendeesImportRequest": { "type": "object", "required": [ "attendees", "idempotency_key" ], "properties": { "attendees": { "type": "array", "minItems": 1, "maxItems": 50000, "items": { "$ref": "#/components/schemas/AttendeeImportRow" }, "description": "At most 50,000 rows per import call; chunk larger rosters." }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" }, "webhook_url": { "$ref": "#/components/schemas/WebhookUrl" } } }, "RunKind": { "type": "string", "enum": [ "import", "enrichment", "match" ] }, "RunStatus": { "type": "string", "enum": [ "queued", "running", "succeeded", "partial", "failed" ] }, "PartnerRun": { "allOf": [ { "type": "object", "required": [ "run_id", "kind", "status", "event_id", "idempotency_key", "progress", "error", "snapshot_metadata", "version_metadata", "webhook_url", "created_at", "updated_at", "started_at", "terminal_at" ], "properties": { "run_id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "$ref": "#/components/schemas/RunKind" }, "status": { "$ref": "#/components/schemas/RunStatus" }, "event_id": { "anyOf": [ { "$ref": "#/components/schemas/PartnerId" }, { "type": "null" } ] }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" }, "progress": { "$ref": "#/components/schemas/JsonObject" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/JsonObject" }, { "type": "null" } ] }, "snapshot_metadata": { "$ref": "#/components/schemas/JsonObject" }, "version_metadata": { "$ref": "#/components/schemas/JsonObject" }, "webhook_url": { "$ref": "#/components/schemas/WebhookUrl" }, "created_at": { "$ref": "#/components/schemas/IsoTimestamp" }, "updated_at": { "$ref": "#/components/schemas/IsoTimestamp" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "terminal_at": { "type": [ "string", "null" ], "format": "date-time" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "PartnerRunWithReplay": { "allOf": [ { "$ref": "#/components/schemas/PartnerRun" }, { "type": "object", "required": [ "idempotent_replay" ], "properties": { "idempotent_replay": { "type": "boolean" } } } ] }, "RunCreateForEventRequest": { "type": "object", "required": [ "idempotency_key" ], "properties": { "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" }, "webhook_url": { "$ref": "#/components/schemas/WebhookUrl" } } }, "MatchRunCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/RunCreateForEventRequest" }, { "type": "object", "properties": { "top_n": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } } ] }, "GenericRunCreateRequest": { "type": "object", "required": [ "kind", "idempotency_key" ], "properties": { "kind": { "$ref": "#/components/schemas/RunKind" }, "idempotency_key": { "$ref": "#/components/schemas/IdempotencyKey" }, "progress": { "$ref": "#/components/schemas/JsonObject" }, "snapshot_metadata": { "$ref": "#/components/schemas/JsonObject" }, "version_metadata": { "$ref": "#/components/schemas/JsonObject" }, "webhook_url": { "$ref": "#/components/schemas/WebhookUrl" } } }, "RunListResponse": { "allOf": [ { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerRun" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "GoalMatch": { "type": [ "object", "null" ], "required": [ "score", "direction" ], "properties": { "score": { "type": "number" }, "direction": { "type": "string", "enum": [ "needsToOffers", "offersToNeeds" ] } }, "description": "Directional best-goal summary. Internal goal UUIDs are not exposed." }, "IntentStrengthSnapshot": { "type": "object", "required": [ "aToB", "bToA" ], "properties": { "aToB": { "type": "number" }, "bToA": { "type": "number" } } }, "MatchObject": { "type": "object", "required": [ "match_id", "run_id", "principal_attendee_id", "target_attendee_id", "final_score", "sub_scores", "best_goal_match", "driving_goal_pair", "intent_strength", "input_hash", "algorithm_version", "policy_version", "context_snapshot_id", "freshness", "computed_at" ], "properties": { "match_id": { "type": "string" }, "run_id": { "$ref": "#/components/schemas/Uuid" }, "principal_attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "target_attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "final_score": { "type": "number" }, "sub_scores": { "type": "object", "required": [ "goal_complementarity", "goal_needs_to_offers", "goal_offers_to_needs", "value_alignment", "general_similarity", "score_a_to_b", "score_b_to_a" ], "properties": { "goal_complementarity": { "type": "number" }, "goal_needs_to_offers": { "type": "number" }, "goal_offers_to_needs": { "type": "number" }, "value_alignment": { "type": "number" }, "general_similarity": { "type": "number" }, "score_a_to_b": { "type": [ "number", "null" ] }, "score_b_to_a": { "type": [ "number", "null" ] } } }, "best_goal_match": { "$ref": "#/components/schemas/GoalMatch" }, "driving_goal_pair": { "$ref": "#/components/schemas/GoalMatch" }, "intent_strength": { "anyOf": [ { "$ref": "#/components/schemas/IntentStrengthSnapshot" }, { "type": "null" } ], "description": "Directional intent-strength snapshot, not a scalar or string." }, "input_hash": { "type": "string" }, "algorithm_version": { "type": [ "string", "null" ] }, "policy_version": { "type": [ "string", "null" ] }, "context_snapshot_id": { "type": [ "string", "null" ] }, "freshness": { "type": "object", "required": [ "computed_at" ], "properties": { "computed_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "computed_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "AttendeeMatchListResponse": { "allOf": [ { "type": "object", "required": [ "event_id", "attendee_id", "run_id", "items", "next_cursor" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "attendee_id": { "$ref": "#/components/schemas/PartnerId" }, "run_id": { "$ref": "#/components/schemas/Uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MatchObject" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "MatchListResponse": { "allOf": [ { "type": "object", "required": [ "event_id", "run_id", "items", "next_cursor" ], "properties": { "event_id": { "$ref": "#/components/schemas/PartnerId" }, "run_id": { "$ref": "#/components/schemas/Uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MatchObject" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "ReviewQueueItem": { "type": "object", "required": [ "review_id", "kind", "partner_id", "display_name", "source_path", "candidate_ref", "confidence", "reasoning", "evaluator", "created_at" ], "properties": { "review_id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "$ref": "#/components/schemas/PartnerKind" }, "partner_id": { "$ref": "#/components/schemas/PartnerId" }, "display_name": { "type": [ "string", "null" ] }, "source_path": { "type": "string" }, "candidate_ref": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "reasoning": { "type": [ "string", "null" ] }, "evaluator": { "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/IsoTimestamp" } } }, "ReviewQueueResponse": { "allOf": [ { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewQueueItem" } }, "next_cursor": { "$ref": "#/components/schemas/Cursor" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "ResolveReviewRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accept", "reject", "distinct" ] }, "reason": { "type": "string" } } }, "ResolveReviewResponse": { "allOf": [ { "type": "object", "required": [ "review_id", "kind", "partner_id", "decision", "logged" ], "properties": { "review_id": { "$ref": "#/components/schemas/Uuid" }, "kind": { "$ref": "#/components/schemas/PartnerKind" }, "partner_id": { "$ref": "#/components/schemas/PartnerId" }, "decision": { "type": "string", "enum": [ "accept", "reject", "distinct" ] }, "logged": { "type": "boolean", "const": true }, "minted": { "type": "boolean", "description": "Present for held import distinct resolutions; true when Meshi minted a new attendee entity." } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "MergeReviewRequest": { "type": "object", "required": [ "source_kind", "source_partner_id", "target_kind", "target_partner_id" ], "properties": { "source_kind": { "$ref": "#/components/schemas/PartnerKind" }, "source_partner_id": { "$ref": "#/components/schemas/PartnerId" }, "target_kind": { "$ref": "#/components/schemas/PartnerKind" }, "target_partner_id": { "$ref": "#/components/schemas/PartnerId" }, "reason": { "type": "string" } } }, "MergeReviewResponse": { "allOf": [ { "type": "object", "required": [ "review_id", "source", "target", "merged", "superseded_anchors", "rewritten_anchors", "deleted_computations" ], "properties": { "review_id": { "$ref": "#/components/schemas/Uuid" }, "source": { "$ref": "#/components/schemas/PartnerRef" }, "target": { "$ref": "#/components/schemas/PartnerRef" }, "merged": { "type": "boolean", "const": true }, "superseded_anchors": { "type": "integer" }, "rewritten_anchors": { "type": "integer" }, "deleted_computations": { "type": "integer" } } }, { "$ref": "#/components/schemas/CorrelationBody" } ] }, "PartnerRef": { "type": "object", "required": [ "kind", "partner_id" ], "properties": { "kind": { "$ref": "#/components/schemas/PartnerKind" }, "partner_id": { "$ref": "#/components/schemas/PartnerId" } } } } } }