{ "openapi": "3.1.0", "info": { "title": "Beans Connect synthetic partner preview", "version": "0.2.0", "description": "Invitation-based, JSON-only PKCE authorization-code preview. Not a general OAuth server. Synthetic organizations only; real vendor and production onboarding are not enabled. 16,384-byte request limit; 1 MB response limit. Server clients only: Origin headers are rejected. All credentials remain in protected partner server custody. See PARTNERS.md for complete direction, retry, deletion and deployment semantics." }, "servers": [ { "url": "http://127.0.0.1:18789", "description": "Disposable local synthetic sandbox only" } ], "paths": { "/partner/v1/authorize": { "post": { "operationId": "beginAuthorization", "summary": "Consume a registered invitation and return a Human review request", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Authorization" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/partner/v1/token": { "post": { "operationId": "exchangeToken", "summary": "Exchange a one-time code or rotate a refresh token", "description": "JSON only. Refresh rotation preserves the original seven-day deadline. Reuse revokes the token family; serialize refreshes and persist results atomically.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CodeExchange" }, { "$ref": "#/components/schemas/RefreshExchange" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tokens" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/partner/v1/connections/{connectionID}/capabilities": { "parameters": [ { "name": "connectionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getCapabilities", "summary": "Check the connection's current partner capabilities", "security": [ { "partnerToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionCapabilities" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/partner/v1/connections/{connectionID}/records": { "parameters": [ { "name": "connectionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listRecords", "summary": "Read this connection's imported records and tombstones", "description": "Requires record:read. Does not expose general Beans notes. Start later scans without a cursor to discover corrections and later inserts.", "security": [ { "partnerToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Last UUID from the previous page of this scan. No other query parameters accepted." } ] }, "post": { "operationId": "ingestRecord", "summary": "Import an immutable source event into the verified pet mapping", "description": "Requires record:read. Retain eventID and payload across retries. Higher source revisions supersede older versions. Tombstones require empty title/body.", "security": [ { "partnerToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEvent" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResult" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/partner/v1/connections/{connectionID}/summary-requests": { "parameters": [ { "name": "connectionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "requestSummary", "summary": "Request a Human-reviewed summary", "description": "Requires summary:submit. Stable event identity. At most 100 unresolved, unexpired requests per connection. The Human may dismiss or send an exact reviewed response; the returned status follows the associated delivery.", "security": [ { "partnerToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryRequestReceipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "get": { "operationId": "readSummaryRequests", "summary": "Inspect request lifecycle and associated delivery", "description": "Scoped request history, including dismissed and completed requests.", "security": [ { "partnerToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryRequestPage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Last UUID from the previous page of this scan. No other query parameters accepted." } ] } }, "/partner/v1/connections/{connectionID}/deliveries": { "parameters": [ { "name": "connectionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "listDeliveries", "summary": "Read delivered summaries and synthetic receipt IDs", "description": "Requires summary:submit. Drafts and queued/unknown deliveries are not exposed. Receipt means adapter receipt, never clinical review.", "security": [ { "partnerToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryPage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Last UUID from the previous page of this scan. No other query parameters accepted." } ] } }, "/partner/v1/connections/{connectionID}/events": { "parameters": [ { "name": "connectionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "readEvents", "summary": "Read durable scoped change events", "description": "Follow hasMore; retain nextCursor after applying each page. Cursor expiry is 24 hours. On 410 bootstrap again: capture a feed checkpoint, scan records, replay from checkpoint. Events contain references, not record content.", "security": [ { "partnerToken": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectEventPage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "405": { "$ref": "#/components/responses/Error405" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "410": { "description": "Cursor expired; rebuild a fresh checkpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 700 } } ] } } }, "components": { "securitySchemes": { "partnerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque 32-byte base64url token" } }, "schemas": { "Capability": { "type": "string", "enum": [ "record:read", "summary:submit" ] }, "Capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" }, "minItems": 1, "maxItems": 2, "uniqueItems": true }, "AuthorizeRequest": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "format": "uuid" }, "invitation": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "redirect_uri": { "type": "string", "format": "uri", "maxLength": 1024, "description": "Exactly registered HTTPS callback; explicit loopback HTTP only for sandbox. No query, fragment or credentials." }, "state": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "code_challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "code_challenge_method": { "const": "S256", "type": "string" } }, "required": [ "client_id", "invitation", "redirect_uri", "state", "code_challenge", "code_challenge_method" ] }, "Authorization": { "type": "object", "additionalProperties": false, "properties": { "requestID": { "type": "string", "format": "uuid" }, "expiresIn": { "type": "integer", "const": 600 } }, "required": [ "requestID", "expiresIn" ] }, "CodeExchange": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "format": "uuid" }, "grant_type": { "type": "string", "const": "authorization_code" }, "code": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" }, "code_verifier": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{43,128}$" }, "redirect_uri": { "type": "string", "format": "uri" } }, "required": [ "client_id", "grant_type", "code", "code_verifier", "redirect_uri" ] }, "RefreshExchange": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "format": "uuid" }, "grant_type": { "type": "string", "const": "refresh_token" }, "refresh_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32,256}$" } }, "required": [ "client_id", "grant_type", "refresh_token" ] }, "Tokens": { "type": "object", "additionalProperties": false, "properties": { "token_type": { "type": "string", "const": "Bearer" }, "access_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "refresh_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expires_in": { "type": "integer", "const": 600 }, "connection_id": { "type": "string", "format": "uuid" }, "capabilities": { "$ref": "#/components/schemas/Capabilities" } }, "required": [ "token_type", "access_token", "refresh_token", "expires_in", "connection_id", "capabilities" ] }, "ConnectionCapabilities": { "type": "object", "additionalProperties": false, "properties": { "connectionID": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "const": "synthetic" }, "capabilities": { "$ref": "#/components/schemas/Capabilities" } }, "required": [ "connectionID", "environment", "capabilities" ] }, "SourceRecord": { "type": "object", "additionalProperties": false, "properties": { "externalID": { "type": "string", "minLength": 1, "maxLength": 180, "x-maxUtf8Bytes": 180, "description": "At most 180 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "sourceRevision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string", "minLength": 0, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; rejects disallowed control characters." }, "body": { "type": "string", "minLength": 0, "maxLength": 4096, "x-maxUtf8Bytes": 4096, "description": "At most 4096 UTF-8 bytes; rejects disallowed control characters." }, "sourceLabel": { "type": "string", "minLength": 1, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "authorRole": { "type": "string", "enum": [ "clinic", "lab" ] }, "observedAt": { "type": "string", "format": "date-time", "description": "No more than five minutes in the future." }, "deleted": { "type": "boolean" } }, "required": [ "externalID", "sourceRevision", "title", "body", "sourceLabel", "authorRole", "observedAt", "deleted" ], "allOf": [ { "if": { "properties": { "deleted": { "const": true } } }, "then": { "properties": { "title": { "maxLength": 0 }, "body": { "maxLength": 0 } } }, "else": { "properties": { "title": { "minLength": 1 }, "body": { "minLength": 1 } } } } ] }, "RecordEvent": { "type": "object", "additionalProperties": false, "properties": { "eventID": { "type": "string", "minLength": 1, "maxLength": 180, "x-maxUtf8Bytes": 180, "description": "At most 180 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "record": { "$ref": "#/components/schemas/SourceRecord" } }, "required": [ "eventID", "record" ] }, "IngestResult": { "type": "object", "additionalProperties": false, "properties": { "accepted": { "type": "boolean", "const": true }, "duplicate": { "type": "boolean" }, "stale": { "type": "boolean" } }, "required": [ "accepted", "duplicate" ] }, "SummaryRequest": { "type": "object", "additionalProperties": false, "properties": { "eventID": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "instructions": { "type": "string", "minLength": 1, "maxLength": 2048, "x-maxUtf8Bytes": 2048, "description": "At most 2048 UTF-8 bytes; nonblank; rejects disallowed control characters." } }, "required": [ "eventID", "title", "instructions" ] }, "SummaryRequestReceipt": { "type": "object", "additionalProperties": false, "required": [ "id", "eventID", "connectionID", "title", "createdAt", "expiresAt", "deliveryID", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "eventID": { "type": "string", "format": "uuid" }, "connectionID": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "deliveryID": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "awaiting_human_review", "response_queued", "completed", "dismissed", "expired", "needs_attention", "delivery_unknown" ] } } }, "Delivery": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "requestID": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "body": { "type": "string", "minLength": 1, "maxLength": 4096, "x-maxUtf8Bytes": 4096, "description": "At most 4096 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "status": { "type": "string", "const": "delivered" }, "receiptID": { "type": "string", "minLength": 1, "maxLength": 256, "x-maxUtf8Bytes": 256, "description": "At most 256 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "requestID", "title", "body", "status", "receiptID", "createdAt", "updatedAt" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" }, "code": { "type": "string" } }, "required": [ "error" ] }, "Record": { "type": "object", "additionalProperties": false, "properties": { "externalID": { "type": "string", "minLength": 1, "maxLength": 180, "x-maxUtf8Bytes": 180, "description": "At most 180 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "sourceRevision": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "title": { "type": "string", "minLength": 0, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; rejects disallowed control characters." }, "body": { "type": "string", "minLength": 0, "maxLength": 4096, "x-maxUtf8Bytes": 4096, "description": "At most 4096 UTF-8 bytes; rejects disallowed control characters." }, "sourceLabel": { "type": "string", "minLength": 1, "maxLength": 160, "x-maxUtf8Bytes": 160, "description": "At most 160 UTF-8 bytes; nonblank; rejects disallowed control characters." }, "authorRole": { "type": "string", "enum": [ "clinic", "lab" ] }, "observedAt": { "type": "string", "format": "date-time", "description": "No more than five minutes in the future." }, "deleted": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "importedAt": { "type": "string", "format": "date-time" } }, "required": [ "externalID", "sourceRevision", "title", "body", "sourceLabel", "authorRole", "observedAt", "deleted", "id", "importedAt" ] }, "RecordPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Record" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid", "description": "Pagination within a scan, not a durable change-feed checkpoint. Restart later scans without a cursor." } }, "required": [ "items", "nextCursor" ] }, "DeliveryPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Delivery" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid", "description": "Pagination within a scan, not a durable change-feed checkpoint. Restart later scans without a cursor." } }, "required": [ "items", "nextCursor" ] }, "SummaryRequestPage": { "type": "object", "required": [ "items", "nextCursor" ], "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/SummaryRequestReceipt" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "ConnectEvent": { "type": "object", "required": [ "revision", "kind", "resourceID", "sourceRevision", "occurredAt" ], "additionalProperties": false, "properties": { "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "kind": { "type": "string", "enum": [ "record.changed", "record.deleted", "summary.delivered" ] }, "resourceID": { "type": "string", "format": "uuid" }, "sourceRevision": { "type": [ "integer", "null" ] }, "occurredAt": { "type": "string", "format": "date-time" } } }, "ConnectEventPage": { "type": "object", "required": [ "items", "nextCursor", "hasMore", "resyncRequired" ], "additionalProperties": false, "properties": { "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ConnectEvent" } }, "nextCursor": { "type": "string", "maxLength": 700 }, "hasMore": { "type": "boolean" }, "resyncRequired": { "type": "boolean", "description": "Retained history no longer covers the initial position. Establish this checkpoint, scan current records, then replay changes from it." } } } }, "responses": { "Error400": { "description": "Invalid request or invalid_grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Missing/malformed bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Current authority unavailable, expired/revoked token or forbidden Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Unknown route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error405": { "description": "Unsupported method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Immutable input or connection changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Application budget or request-history cap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Disabled or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }