{ "openapi": "3.1.0", "info": { "title": "Singularity API", "version": "1.0.0", "description": "Stable public contract for the core Singularity outreach memory and policy API.", "license": { "name": "Proprietary", "url": "https://memory.conseqai.com" } }, "servers": [ { "url": "https://memory.conseqai.com", "description": "Production" }, { "url": "http://localhost:8080", "description": "Local development" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "public", "description": "Unauthenticated public read endpoints." }, { "name": "contactability", "description": "Read-before-send policy evaluation." }, { "name": "events", "description": "Append-only outreach history reads and writes." }, { "name": "targets", "description": "Target history, summaries, and policy exports." }, { "name": "imports", "description": "Durable background import jobs." }, { "name": "webhooks", "description": "Webhook subscriptions, delivery inspection, and replay." }, { "name": "flags", "description": "Trust and dispute flagging writes." }, { "name": "decisions", "description": "Stored policy decision audit reads." }, { "name": "records", "description": "Typed record links and portable external references." }, { "name": "federation", "description": "Federated signal exchange, query, dispute, and override routes." } ], "paths": { "/api/public/macro-trends": { "get": { "operationId": "getPublicMacroTrends", "tags": [ "public" ], "summary": "Read public global macro trends", "security": [], "responses": { "200": { "description": "Public aggregate macro trend summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMacroTrends" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/contactability/check": { "post": { "operationId": "checkContactability", "tags": [ "contactability" ], "summary": "Evaluate whether contact is allowed now", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactabilityCheckRequest" } } } }, "responses": { "200": { "description": "Contactability decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactabilityDecision" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/outreach-events": { "get": { "operationId": "listOutreachEvents", "tags": [ "events" ], "summary": "List outreach events", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "personId", "in": "query", "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "schema": { "type": "string" } }, { "name": "ideaId", "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "in": "query", "schema": { "type": "string" } }, { "name": "eventType", "in": "query", "schema": { "type": "string" } }, { "name": "sourceSystem", "in": "query", "schema": { "type": "string" } }, { "name": "actorType", "in": "query", "schema": { "type": "string" } }, { "name": "actorIdentifier", "in": "query", "schema": { "type": "string" } }, { "name": "trustState", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Recent outreach events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutreachEventListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "createOutreachEvent", "tags": [ "events" ], "summary": "Append a single outreach fact", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/SignedWriteSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutreachEventRequest" } } } }, "responses": { "201": { "description": "Stored outreach event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutreachEvent" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/ideas": { "get": { "operationId": "listIdeas", "tags": [ "ideas" ], "summary": "List recorded ideas for a tenant", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "proposed", "in_progress", "done", "not_doing" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Ideas for the tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "createIdea", "tags": [ "ideas" ], "summary": "Create a new idea record", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdeaRequest" } } } }, "responses": { "201": { "description": "Created idea", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Idea" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/ideas/{id}": { "get": { "operationId": "getIdea", "tags": [ "ideas" ], "summary": "Fetch a single idea", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Idea record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Idea" } } } }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "patch": { "operationId": "updateIdea", "tags": [ "ideas" ], "summary": "Update an idea record", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIdeaRequest" } } } }, "responses": { "200": { "description": "Updated idea", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Idea" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/ideas/{id}/summary": { "get": { "operationId": "getIdeaSummary", "tags": [ "ideas" ], "summary": "Return outreach-derived summary for an idea", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Idea summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaSummary" } } } }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/targets/summary": { "post": { "operationId": "getTargetSummary", "tags": [ "targets" ], "summary": "Resolve a target and return the compact current-state view", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetSummaryRequest" } } } }, "responses": { "200": { "description": "Target summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetSummaryResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/targets/history": { "post": { "operationId": "getTargetHistory", "tags": [ "targets" ], "summary": "Resolve a target and return recent outreach history", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetHistoryRequest" } } } }, "responses": { "200": { "description": "Target history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/targets/policy-document": { "post": { "operationId": "getPolicyDocument", "tags": [ "targets" ], "summary": "Export the active portable policy document", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetSummaryRequest" } } } }, "responses": { "200": { "description": "Portable policy.v1 document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDocument" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/imports/outreach-csv": { "get": { "operationId": "listOutreachCSVImports", "tags": [ "imports" ], "summary": "List outreach CSV import jobs", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Recent outreach CSV import jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJobListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "createOutreachCSVImport", "tags": [ "imports" ], "summary": "Enqueue an outreach CSV import job", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutreachCSVImportRequest" } } } }, "responses": { "202": { "description": "Queued import job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/imports/outreach-csv/{id}": { "get": { "operationId": "getOutreachCSVImport", "tags": [ "imports" ], "summary": "Read a single outreach CSV import job", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportJob" } } } }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "webhooks" ], "summary": "List webhook subscriptions for a tenant", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "createWebhook", "tags": [ "webhooks" ], "summary": "Create a webhook subscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookSubscriptionRequest" } } } }, "responses": { "201": { "description": "Stored webhook subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/webhooks/{id}": { "delete": { "operationId": "revokeWebhook", "tags": [ "webhooks" ], "summary": "Deactivate a webhook subscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Webhook subscription deactivated" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "webhooks" ], "summary": "List delivery records for a webhook subscription", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Recent webhook deliveries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "operationId": "replayWebhookDelivery", "tags": [ "webhooks" ], "summary": "Replay a failed or dead-letter webhook delivery", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Requeued webhook delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/operations/history": { "get": { "operationId": "listOperationsHistory", "tags": [ "operations" ], "summary": "List persisted import and webhook queue history", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "import_job", "webhook_delivery" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Persisted async operation history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationHistoryListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/record-flags": { "post": { "operationId": "createRecordFlag", "tags": [ "flags" ], "summary": "Create a record flag instead of mutating history", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "$ref": "#/components/parameters/SignedWriteSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecordFlagRequest" } } } }, "responses": { "201": { "description": "Stored record flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordFlag" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/policy-decisions": { "get": { "operationId": "listPolicyDecisions", "tags": [ "decisions" ], "summary": "List stored policy decisions", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "personId", "in": "query", "schema": { "type": "string" } }, { "name": "organizationId", "in": "query", "schema": { "type": "string" } }, { "name": "identityType", "in": "query", "schema": { "type": "string" } }, { "name": "identityValue", "in": "query", "schema": { "type": "string" } }, { "name": "channelId", "in": "query", "schema": { "type": "string" } }, { "name": "actorType", "in": "query", "schema": { "type": "string" } }, { "name": "actorIdentifier", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "evaluatedAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "evaluatedBefore", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Stored policy decisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyDecisionListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/record-links": { "get": { "operationId": "listRecordLinks", "tags": [ "records" ], "summary": "List typed links for a record", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "tableName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Record links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordLinkListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "createRecordLink", "tags": [ "records" ], "summary": "Create a typed link between two records", "parameters": [ { "$ref": "#/components/parameters/SignedWriteSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecordLinkRequest" } } } }, "responses": { "201": { "description": "Record link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordLink" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/external-references": { "get": { "operationId": "listExternalReferences", "tags": [ "records" ], "summary": "List external references for a record", "parameters": [ { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "tableName", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "recordId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "External references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReferenceListResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } }, "post": { "operationId": "upsertExternalReference", "tags": [ "records" ], "summary": "Upsert a portable external identifier for a record", "parameters": [ { "$ref": "#/components/parameters/SignedWriteSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertExternalReferenceRequest" } } } }, "responses": { "201": { "description": "External reference created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReference" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/federation/query": { "post": { "operationId": "queryFederation", "tags": [ "federation" ], "summary": "Query exact-match federated signals for a subject and channel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationQueryRequest" } } } }, "responses": { "200": { "description": "Federation query result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationQueryResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/federation/signals": { "post": { "operationId": "createFederationSignal", "tags": [ "federation" ], "summary": "Append a signed federated signal with optional evidence links", "parameters": [ { "$ref": "#/components/parameters/SignedWriteSignatureHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestFederationSignalRequest" } } } }, "responses": { "201": { "description": "Federated signal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSignal" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/federation/disputes": { "post": { "operationId": "createFederationDispute", "tags": [ "federation" ], "summary": "Open a dispute on a federated signal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFederationDisputeRequest" } } } }, "responses": { "201": { "description": "Federated signal dispute created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSignalDispute" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/api/federation/overrides": { "post": { "operationId": "createFederationOverride", "tags": [ "federation" ], "summary": "Create a local override for a federated signal", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFederationOverrideRequest" } } } }, "responses": { "201": { "description": "Federated signal override created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederatedSignalOverride" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" } }, "parameters": { "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Stable write key required for external_agent writes.", "schema": { "type": "string" } }, "SignedWriteSignatureHeader": { "name": "X-Singularity-Signature", "in": "header", "required": false, "description": "Base64 Ed25519 signature over the raw JSON request body for API keys configured for signed writes.", "schema": { "type": "string" } } }, "responses": { "ErrorResponse": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "code", "error" ], "properties": { "code": { "type": "string" }, "error": { "type": "string" } } }, "JsonObjectNullable": { "type": [ "object", "null" ], "additionalProperties": true }, "WriteActor": { "type": "object", "required": [ "actorType", "actorIdentifier" ], "properties": { "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "EventSource": { "type": "object", "required": [ "sourceSystem", "ingestionMethod" ], "properties": { "sourceSystem": { "type": "string" }, "sourceRecordId": { "type": "string" }, "ingestionMethod": { "type": "string" } } }, "EventTarget": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" } } }, "EventEnvelope": { "type": "object", "required": [ "schemaVersion", "tenantId", "channelId", "eventType", "direction", "occurredAt", "target", "actor", "source" ], "properties": { "schemaVersion": { "type": "string" }, "idempotencyKey": { "type": "string" }, "tenantId": { "type": "string" }, "ideaId": { "type": "string" }, "channelId": { "type": "string" }, "eventType": { "type": "string" }, "direction": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "target": { "$ref": "#/components/schemas/EventTarget" }, "actor": { "$ref": "#/components/schemas/WriteActor" }, "source": { "$ref": "#/components/schemas/EventSource" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" } } }, "OutreachEvent": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "ideaId", "agentId", "campaignId", "channelId", "performedByUserId", "eventType", "direction", "outcome", "subject", "bodyPreview", "occurredAt", "sourceSystem", "sourceRecordId", "ingestionMethod", "actorType", "actorIdentifier", "eventSchemaVersion", "idempotencyKey", "trustState", "envelope", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "ideaId": { "type": "string" }, "agentId": { "type": "string" }, "campaignId": { "type": "string" }, "channelId": { "type": "string" }, "performedByUserId": { "type": "string" }, "eventType": { "type": "string" }, "direction": { "type": "string" }, "outcome": { "type": "string" }, "subject": { "type": "string" }, "bodyPreview": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "sourceSystem": { "type": "string" }, "sourceRecordId": { "type": "string" }, "ingestionMethod": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "eventSchemaVersion": { "type": "string" }, "idempotencyKey": { "type": "string" }, "trustState": { "type": "string" }, "envelope": { "$ref": "#/components/schemas/EventEnvelope" }, "createdAt": { "type": "string", "format": "date-time" } } }, "OutreachEventListResponse": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutreachEvent" } } } }, "Idea": { "type": "object", "required": [ "id", "tenantId", "title", "normalizedTitle", "summary", "status", "outcomeSummary", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "title": { "type": "string" }, "normalizedTitle": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "in_progress", "done", "not_doing" ] }, "outcomeSummary": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "IdeaTargetSummary": { "type": "object", "required": [ "targetKind", "targetName", "attemptCount", "totalEventCount", "replyCount", "meetingCount", "latestEventType", "latestOutcome" ], "properties": { "targetKind": { "type": "string", "enum": [ "person", "organization" ] }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "targetName": { "type": "string" }, "attemptCount": { "type": "integer" }, "totalEventCount": { "type": "integer" }, "replyCount": { "type": "integer" }, "meetingCount": { "type": "integer" }, "latestEventType": { "type": "string" }, "latestOutcome": { "type": "string" }, "latestOccurredAt": { "type": "string", "format": "date-time" } } }, "IdeaSummary": { "type": "object", "required": [ "ideaId", "tenantId", "tried", "totalTargets", "totalAttempts", "totalEvents", "totalReplies", "totalMeetings", "recentEvents", "targets", "evidenceLinks", "externalReferences" ], "properties": { "ideaId": { "type": "string" }, "tenantId": { "type": "string" }, "tried": { "type": "boolean" }, "totalTargets": { "type": "integer" }, "totalAttempts": { "type": "integer" }, "totalEvents": { "type": "integer" }, "totalReplies": { "type": "integer" }, "totalMeetings": { "type": "integer" }, "recentEvents": { "type": "array", "items": { "$ref": "#/components/schemas/OutreachEvent" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/IdeaTargetSummary" } }, "evidenceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLink" } }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "IdeaListResponse": { "type": "object", "required": [ "ideas" ], "properties": { "ideas": { "type": "array", "items": { "$ref": "#/components/schemas/Idea" } } } }, "PolicyCheck": { "type": "object", "required": [ "ruleType", "status", "code", "message" ], "properties": { "ruleType": { "type": "string" }, "status": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "source": { "type": "string" } } }, "FederatedSignalSubject": { "type": "object", "required": [ "identityType", "identityValue", "normalizedValue", "matchKey" ], "properties": { "identityType": { "type": "string" }, "identityValue": { "type": "string" }, "normalizedValue": { "type": "string" }, "matchKey": { "type": "string" } } }, "FederatedSignal": { "type": "object", "required": [ "id", "tenantId", "shareScope", "partnerId", "partnerName", "partnerKeyId", "signalType", "channelRef", "observedAt", "sourceSystem", "sourceRecordId", "actorType", "actorIdentifier", "reasonCode", "evidenceType", "evidenceHash", "notes", "trustTier", "trustState", "hasOpenDispute", "createdAt", "subject", "evidenceLinks", "externalReferences" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "shareScope": { "type": "string" }, "partnerId": { "type": "string" }, "partnerName": { "type": "string" }, "partnerKeyId": { "type": "string" }, "signalType": { "type": "string" }, "channelRef": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "sourceSystem": { "type": "string" }, "sourceRecordId": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "reasonCode": { "type": "string" }, "evidenceType": { "type": "string" }, "evidenceHash": { "type": "string" }, "notes": { "type": "string" }, "trustTier": { "type": "string" }, "trustState": { "type": "string" }, "hasOpenDispute": { "type": "boolean" }, "activeOverrideAction": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "subject": { "$ref": "#/components/schemas/FederatedSignalSubject" }, "evidenceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLink" } }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "FederationEvaluation": { "type": "object", "required": [ "included", "matchedCount", "signals" ], "properties": { "included": { "type": "boolean" }, "matchedCount": { "type": "integer" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/FederatedSignal" } } } }, "ContactabilityDecision": { "type": "object", "required": [ "allowed", "status", "reasons", "checks", "evaluatedAt" ], "properties": { "allowed": { "type": "boolean" }, "status": { "type": "string", "enum": [ "allow", "deny", "review" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyCheck" } }, "federation": { "$ref": "#/components/schemas/FederationEvaluation" }, "evaluatedAt": { "type": "string", "format": "date-time" } } }, "ResolvedTarget": { "type": "object", "required": [ "canonicalType", "canonicalId", "personId", "organizationId", "matchedBy", "matchedValue", "identityType", "identityValue", "identitySource", "reviewStatus", "matchConfidence" ], "properties": { "canonicalType": { "type": "string" }, "canonicalId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "matchedBy": { "type": "string" }, "matchedValue": { "type": "string" }, "identityType": { "type": "string" }, "identityValue": { "type": "string" }, "identitySource": { "type": "string" }, "reviewStatus": { "type": "string" }, "matchConfidence": { "type": "number" } } }, "ContactIdentity": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "identityType", "identityValue", "normalizedValue", "isPrimary", "source", "matchConfidence", "reviewStatus", "trustState", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "identityType": { "type": "string" }, "identityValue": { "type": "string" }, "normalizedValue": { "type": "string" }, "isPrimary": { "type": "boolean" }, "source": { "type": "string" }, "matchConfidence": { "type": "number" }, "reviewStatus": { "type": "string" }, "trustState": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ContactPreference": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "preferredChannels", "blockedChannels", "notes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "preferredChannels": { "type": "array", "items": { "type": "string" } }, "blockedChannels": { "type": "array", "items": { "type": "string" } }, "preferredContactWindow": { "$ref": "#/components/schemas/JsonObjectNullable" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OptOutSignal": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "channelId", "signalType", "reason", "source", "isHardBlock", "trustState", "idempotencyKey", "effectiveAt", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "channelId": { "type": "string" }, "signalType": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "isHardBlock": { "type": "boolean" }, "trustState": { "type": "string" }, "idempotencyKey": { "type": "string" }, "effectiveAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CooldownWindow": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "channelId", "reason", "source", "startsAt", "endsAt", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "channelId": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "BackOffRule": { "type": "object", "required": [ "id", "tenantId", "targetPersonId", "targetOrganizationId", "channelId", "name", "scopeType", "maxOutboundEvents", "windowDays", "minimumGapHours", "priority", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "targetPersonId": { "type": "string" }, "targetOrganizationId": { "type": "string" }, "channelId": { "type": "string" }, "name": { "type": "string" }, "scopeType": { "type": "string" }, "maxOutboundEvents": { "type": "integer" }, "windowDays": { "type": "integer" }, "minimumGapHours": { "type": "integer" }, "priority": { "type": "integer" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PolicyDecision": { "type": "object", "required": [ "id", "tenantId", "personId", "organizationId", "channelId", "actorType", "actorIdentifier", "decisionStatus", "reasonSummary", "evaluatedAt", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "channelId": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "decisionStatus": { "type": "string" }, "reasonSummary": { "type": "string" }, "evaluatedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PolicySnapshot": { "type": "object", "required": [ "target", "channelId", "preferences", "optOutSignals", "cooldownWindows", "backOffRules", "recentDecisions" ], "properties": { "target": { "$ref": "#/components/schemas/ResolvedTarget" }, "channelId": { "type": "string" }, "preferences": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPreference" } }, "optOutSignals": { "type": "array", "items": { "$ref": "#/components/schemas/OptOutSignal" } }, "cooldownWindows": { "type": "array", "items": { "$ref": "#/components/schemas/CooldownWindow" } }, "backOffRules": { "type": "array", "items": { "$ref": "#/components/schemas/BackOffRule" } }, "recentDecisions": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyDecision" } } } }, "TargetHistoryResponse": { "type": "object", "required": [ "target", "events" ], "properties": { "target": { "$ref": "#/components/schemas/ResolvedTarget" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutreachEvent" } } } }, "TargetSummaryResponse": { "type": "object", "required": [ "target", "identities", "recentEvents", "policy", "evidenceLinks", "externalReferences" ], "properties": { "target": { "$ref": "#/components/schemas/ResolvedTarget" }, "identities": { "type": "array", "items": { "$ref": "#/components/schemas/ContactIdentity" } }, "recentEvents": { "type": "array", "items": { "$ref": "#/components/schemas/OutreachEvent" } }, "policy": { "$ref": "#/components/schemas/PolicySnapshot" }, "evidenceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLink" } }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "PolicyInheritance": { "type": "object", "required": [ "tenantDefaultsApply", "organizationRulesPresent", "personRulesPresent", "effectiveScopes", "overrideBehavior" ], "properties": { "tenantDefaultsApply": { "type": "boolean" }, "organizationRulesPresent": { "type": "boolean" }, "personRulesPresent": { "type": "boolean" }, "effectiveScopes": { "type": "array", "items": { "type": "string" } }, "overrideBehavior": { "type": "string" } } }, "PolicyEffectiveWindow": { "type": "object", "properties": { "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } } }, "PortablePolicyRule": { "type": "object", "required": [ "ruleId", "ruleType", "scope", "effective", "action", "reasonCode", "description" ], "properties": { "ruleId": { "type": "string" }, "ruleType": { "type": "string" }, "scope": { "type": "string" }, "effective": { "type": "boolean" }, "channelId": { "type": "string" }, "action": { "type": "string" }, "reasonCode": { "type": "string" }, "description": { "type": "string" }, "effectiveWindow": { "$ref": "#/components/schemas/PolicyEffectiveWindow" }, "parameters": { "$ref": "#/components/schemas/JsonObjectNullable" }, "source": { "type": "string" } } }, "PolicyExplanationDescriptor": { "type": "object", "required": [ "code", "ruleType", "status", "description" ], "properties": { "code": { "type": "string" }, "ruleType": { "type": "string" }, "status": { "type": "string" }, "description": { "type": "string" } } }, "PolicyDocument": { "type": "object", "required": [ "version", "generatedAt", "target", "channelId", "coreRuleTypes", "rulePrecedence", "overrideBehavior", "inheritance", "rules", "explanationCatalog", "evidenceLinks", "targetExternalReferences" ], "properties": { "version": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "target": { "$ref": "#/components/schemas/ResolvedTarget" }, "channelId": { "type": "string" }, "coreRuleTypes": { "type": "array", "items": { "type": "string" } }, "rulePrecedence": { "type": "array", "items": { "type": "string" } }, "overrideBehavior": { "type": "string" }, "inheritance": { "$ref": "#/components/schemas/PolicyInheritance" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/PortablePolicyRule" } }, "explanationCatalog": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyExplanationDescriptor" } }, "evidenceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLink" } }, "targetExternalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "ImportRowError": { "type": "object", "required": [ "row", "message" ], "properties": { "row": { "type": "integer" }, "message": { "type": "string" } } }, "ImportJob": { "type": "object", "required": [ "id", "tenantId", "importType", "status", "sourceSystem", "actorType", "actorIdentifier", "totalRows", "importedCount", "duplicateCount", "failedCount", "errors", "attemptCount", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "importType": { "type": "string", "enum": [ "outreach_csv" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "totalRows": { "type": "integer" }, "importedCount": { "type": "integer" }, "duplicateCount": { "type": "integer" }, "failedCount": { "type": "integer" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ImportRowError" } }, "attemptCount": { "type": "integer" }, "lastError": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } } }, "ImportJobListResponse": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJob" } } } }, "CreateWebhookSubscriptionRequest": { "type": "object", "required": [ "tenantId", "name", "targetUrl", "eventTypes", "signingSecret" ], "properties": { "tenantId": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "outreach_event.created", "policy_decision.created" ] } }, "signingSecret": { "type": "string" } } }, "WebhookSubscription": { "type": "object", "required": [ "id", "tenantId", "name", "targetUrl", "eventTypes", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "outreach_event.created", "policy_decision.created" ] } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionListResponse": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "subscriptionId", "tenantId", "eventType", "resourceId", "deliveryStatus", "errorMessage", "requestPayload", "attemptCount", "createdAt" ], "properties": { "id": { "type": "string" }, "subscriptionId": { "type": "string" }, "tenantId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "outreach_event.created", "policy_decision.created" ] }, "resourceId": { "type": "string" }, "deliveryStatus": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed", "dead_letter" ] }, "responseStatus": { "type": "integer" }, "errorMessage": { "type": "string" }, "requestPayload": { "type": "object", "additionalProperties": true }, "attemptCount": { "type": "integer" }, "attemptedAt": { "type": "string", "format": "date-time" }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookDeliveryListResponse": { "type": "object", "required": [ "deliveries" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "OperationHistoryEntry": { "type": "object", "required": [ "id", "tenantId", "operationKind", "operationId", "status", "event", "summary", "details", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "operationKind": { "type": "string", "enum": [ "import_job", "webhook_delivery" ] }, "operationId": { "type": "string" }, "status": { "type": "string" }, "event": { "type": "string", "enum": [ "queued", "started", "retry_started", "attempt_started", "completed", "failed", "delivered", "dead_lettered", "replayed" ] }, "summary": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "OperationHistoryListResponse": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/OperationHistoryEntry" } } } }, "RecordFlag": { "type": "object", "required": [ "id", "tenantId", "tableName", "recordId", "flagType", "status", "description", "actorType", "actorIdentifier", "resolutionNotes", "resolutionCode", "idempotencyKey", "baselineTrustState", "resolvedByUserId", "resolvedByAgentId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "tableName": { "type": "string" }, "recordId": { "type": "string" }, "flagType": { "type": "string" }, "status": { "type": "string" }, "description": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "flaggedByUserId": { "type": "string" }, "flaggedByAgentId": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "resolutionNotes": { "type": "string" }, "resolutionCode": { "type": "string" }, "idempotencyKey": { "type": "string" }, "baselineTrustState": { "type": "string" }, "resolvedByUserId": { "type": "string" }, "resolvedByAgentId": { "type": "string" }, "resolvedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PolicyDecisionListResponse": { "type": "object", "required": [ "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyDecision" } } } }, "MacroSourceStat": { "type": "object", "required": [ "sourceSystem", "eventCount", "negativeSignalCount" ], "properties": { "sourceSystem": { "type": "string" }, "eventCount": { "type": "integer" }, "negativeSignalCount": { "type": "integer" } } }, "PublicMacroPrivacy": { "type": "object", "required": [ "minimumPublisherThreshold", "publisherThresholdMet", "activePublishersBucket", "networkStage" ], "properties": { "minimumPublisherThreshold": { "type": "integer" }, "publisherThresholdMet": { "type": "boolean" }, "activePublishersBucket": { "type": "string" }, "networkStage": { "type": "string" }, "redactedFields": { "type": "array", "items": { "type": "string" } } } }, "PublicMacroFreshness": { "type": "object", "required": [ "summaryWindowDays", "trendWindowDays", "cacheTtlSeconds" ], "properties": { "summaryWindowDays": { "type": "integer" }, "trendWindowDays": { "type": "integer" }, "cacheTtlSeconds": { "type": "integer" } } }, "PublicGlobalMacroSummary": { "type": "object", "properties": { "activeWorkspacesLast30Days": { "type": "integer" }, "claimedDomains": { "type": "integer" }, "verifiedDomains": { "type": "integer" }, "globalSignalsLast30Days": { "type": "integer" }, "optOutSignalsLast30Days": { "type": "integer" }, "hardBounceSignalsLast30Days": { "type": "integer" }, "complaintSignalsLast30Days": { "type": "integer" } } }, "PublicGlobalTrendPoint": { "type": "object", "required": [ "date" ], "properties": { "date": { "type": "string" }, "signals": { "type": "integer" }, "publishers": { "type": "integer" } } }, "PublicMacroTrends": { "type": "object", "required": [ "generatedAt", "privacy", "freshness", "global", "globalSeries", "topSources" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "privacy": { "$ref": "#/components/schemas/PublicMacroPrivacy" }, "freshness": { "$ref": "#/components/schemas/PublicMacroFreshness" }, "global": { "$ref": "#/components/schemas/PublicGlobalMacroSummary" }, "globalSeries": { "type": "array", "items": { "$ref": "#/components/schemas/PublicGlobalTrendPoint" } }, "topSources": { "type": "array", "items": { "$ref": "#/components/schemas/MacroSourceStat" } } } }, "TargetLookupRequest": { "type": "object", "required": [ "tenantId" ], "properties": { "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "identityType": { "type": "string" }, "identityValue": { "type": "string" } }, "description": "Provide exactly one lookup mode: personId, organizationId, or identityType + identityValue." }, "ContactabilityCheckRequest": { "allOf": [ { "$ref": "#/components/schemas/TargetLookupRequest" }, { "type": "object", "required": [ "channelId" ], "properties": { "channelId": { "type": "string" }, "includeFederation": { "type": "boolean" }, "federationTrustFloor": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } } ] }, "CreateOutreachEventRequest": { "type": "object", "required": [ "tenantId", "channelId", "eventType" ], "properties": { "tenantId": { "type": "string" }, "personId": { "type": "string" }, "organizationId": { "type": "string" }, "ideaId": { "type": "string" }, "agentId": { "type": "string" }, "campaignId": { "type": "string" }, "channelId": { "type": "string" }, "performedByUserId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "contact_attempt", "reply", "meeting", "unsubscribe", "bounce", "note" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "outcome": { "type": "string" }, "subject": { "type": "string" }, "bodyPreview": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "sourceSystem": { "type": "string" }, "sourceRecordId": { "type": "string" }, "ingestionMethod": { "type": "string" }, "idempotencyKey": { "type": "string" }, "eventSchemaVersion": { "type": "string", "default": "singularity.event.v1" } }, "description": "Provide exactly one of personId or organizationId. ideaId is optional." }, "CreateIdeaRequest": { "type": "object", "required": [ "tenantId", "title" ], "properties": { "tenantId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "in_progress", "done", "not_doing" ] }, "outcomeSummary": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "UpdateIdeaRequest": { "type": "object", "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "in_progress", "done", "not_doing" ] }, "outcomeSummary": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "TargetSummaryRequest": { "allOf": [ { "$ref": "#/components/schemas/TargetLookupRequest" }, { "type": "object", "properties": { "channelId": { "type": "string" }, "eventLimit": { "type": "integer" }, "decisionLimit": { "type": "integer" } } } ] }, "TargetHistoryRequest": { "allOf": [ { "$ref": "#/components/schemas/TargetLookupRequest" }, { "type": "object", "properties": { "channelId": { "type": "string" }, "eventType": { "type": "string" }, "sourceSystem": { "type": "string" }, "limit": { "type": "integer" } } } ] }, "OutreachCSVImportRequest": { "type": "object", "required": [ "tenantId", "csv" ], "description": "The CSV may include optional ideaId or ideaTitle columns so imported outreach rows can link to ideas.", "properties": { "tenantId": { "type": "string" }, "csv": { "type": "string", "description": "Normalized outreach CSV. Optional headers include ideaId and ideaTitle." }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "CreateRecordFlagRequest": { "type": "object", "required": [ "tenantId", "tableName", "recordId", "flagType", "description" ], "properties": { "tenantId": { "type": "string" }, "tableName": { "type": "string" }, "recordId": { "type": "string" }, "flagType": { "type": "string", "enum": [ "disputed", "bad_data", "malicious" ] }, "description": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "flaggedByUserId": { "type": "string" }, "flaggedByAgentId": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "idempotencyKey": { "type": "string" } } }, "SignedWriteProvenance": { "type": "object", "required": [ "verified" ], "properties": { "keyId": { "type": "string" }, "algorithm": { "type": "string" }, "payloadHash": { "type": "string" }, "verified": { "type": "boolean" } } }, "RecordLink": { "type": "object", "required": [ "id", "tenantId", "sourceTable", "sourceId", "targetTable", "targetId", "linkType", "metadata", "sourceSystem", "actorType", "actorIdentifier", "signedWrite", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "sourceTable": { "type": "string" }, "sourceId": { "type": "string" }, "targetTable": { "type": "string" }, "targetId": { "type": "string" }, "linkType": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "signedWrite": { "$ref": "#/components/schemas/SignedWriteProvenance" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ExternalReference": { "type": "object", "required": [ "id", "tenantId", "tableName", "recordId", "externalSystem", "referenceType", "externalId", "metadata", "sourceSystem", "actorType", "actorIdentifier", "signedWrite", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "tableName": { "type": "string" }, "recordId": { "type": "string" }, "externalSystem": { "type": "string" }, "referenceType": { "type": "string" }, "externalId": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "signedWrite": { "$ref": "#/components/schemas/SignedWriteProvenance" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RecordLinkListResponse": { "type": "object", "required": [ "links" ], "properties": { "links": { "type": "array", "items": { "$ref": "#/components/schemas/RecordLink" } } } }, "ExternalReferenceListResponse": { "type": "object", "required": [ "externalReferences" ], "properties": { "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReference" } } } }, "CreateRecordLinkRequest": { "type": "object", "required": [ "tenantId", "sourceTable", "sourceId", "targetTable", "targetId", "linkType" ], "properties": { "tenantId": { "type": "string" }, "sourceTable": { "type": "string" }, "sourceId": { "type": "string" }, "targetTable": { "type": "string" }, "targetId": { "type": "string" }, "linkType": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "UpsertExternalReferenceRequest": { "type": "object", "required": [ "tenantId", "tableName", "recordId", "externalSystem", "referenceType", "externalId" ], "properties": { "tenantId": { "type": "string" }, "tableName": { "type": "string" }, "recordId": { "type": "string" }, "externalSystem": { "type": "string" }, "referenceType": { "type": "string" }, "externalId": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" }, "sourceSystem": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "FederationSignalSubjectInput": { "type": "object", "required": [ "identityType", "identityValue" ], "properties": { "identityType": { "type": "string" }, "identityValue": { "type": "string" } } }, "FederationSignalSource": { "type": "object", "required": [ "sourceSystem", "actorIdentifier" ], "properties": { "sourceSystem": { "type": "string" }, "sourceRecordId": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "FederationSignalEvidence": { "type": "object", "required": [ "reasonCode" ], "properties": { "reasonCode": { "type": "string" }, "evidenceType": { "type": "string" }, "evidenceHash": { "type": "string" }, "notes": { "type": "string" } } }, "FederationSignalLink": { "type": "object", "required": [ "targetTable", "targetId", "linkType" ], "properties": { "targetTable": { "type": "string" }, "targetId": { "type": "string" }, "linkType": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" } } }, "FederationSignalExternalReference": { "type": "object", "required": [ "externalSystem", "referenceType", "externalId" ], "properties": { "externalSystem": { "type": "string" }, "referenceType": { "type": "string" }, "externalId": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObjectNullable" } } }, "IngestFederationSignalRequest": { "type": "object", "required": [ "tenantId", "version", "shareScope", "partnerId", "partnerKeyId", "signalType", "channelId", "observedAt", "subject", "source", "evidence", "signature" ], "properties": { "tenantId": { "type": "string" }, "version": { "type": "string" }, "shareScope": { "type": "string" }, "partnerId": { "type": "string" }, "partnerKeyId": { "type": "string" }, "signalType": { "type": "string" }, "channelId": { "type": "string" }, "observedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "subject": { "$ref": "#/components/schemas/FederationSignalSubjectInput" }, "source": { "$ref": "#/components/schemas/FederationSignalSource" }, "evidence": { "$ref": "#/components/schemas/FederationSignalEvidence" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/FederationSignalLink" } }, "externalReferences": { "type": "array", "items": { "$ref": "#/components/schemas/FederationSignalExternalReference" } }, "signature": { "type": "string" } } }, "FederationQueryRequest": { "type": "object", "required": [ "tenantId", "channelId", "subject" ], "properties": { "tenantId": { "type": "string" }, "channelId": { "type": "string" }, "federationTrustFloor": { "type": "string" }, "subject": { "$ref": "#/components/schemas/FederationSignalSubjectInput" } } }, "FederationQueryResponse": { "type": "object", "required": [ "signals" ], "properties": { "signals": { "type": "array", "items": { "$ref": "#/components/schemas/FederatedSignal" } } } }, "CreateFederationDisputeRequest": { "type": "object", "required": [ "tenantId", "signalId", "description" ], "properties": { "tenantId": { "type": "string" }, "signalId": { "type": "string" }, "description": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "FederatedSignalDispute": { "type": "object", "required": [ "id", "tenantId", "signalId", "status", "description", "actorType", "actorIdentifier", "resolutionNotes", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "signalId": { "type": "string" }, "status": { "type": "string" }, "description": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "resolutionNotes": { "type": "string" }, "resolvedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateFederationOverrideRequest": { "type": "object", "required": [ "tenantId", "signalId", "reason" ], "properties": { "tenantId": { "type": "string" }, "signalId": { "type": "string" }, "overrideAction": { "type": "string" }, "reason": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" } } }, "FederatedSignalOverride": { "type": "object", "required": [ "id", "tenantId", "signalId", "overrideAction", "reason", "actorType", "actorIdentifier", "createdAt" ], "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "signalId": { "type": "string" }, "overrideAction": { "type": "string" }, "reason": { "type": "string" }, "actorType": { "type": "string" }, "actorIdentifier": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }