{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","x-povento-data-contract":{"$ref":"./data-contract.schema.json"},"x-povento-data-permissions":{"read":"data:read","write":"data:write","schema":"data:schema","import":"data:import","export":"data:export","admin":"data:admin"},"info":{"title":"Povento Platform API","version":"1.0.0","description":"Composable tenant-scoped APIs for solutions that adopt none, some, or all of the platform capabilities, including commerce, access, communications, support, and BOOS registration."},"servers":[{"url":"/api","description":"All path keys below are relative to this /api base; for example, /agent/operations resolves to /api/agent/operations."}],"security":[{"bearerAuth":[]}],"paths":{"/projects":{"get":{"summary":"List account-scoped projects","responses":{"200":{"description":"Projects visible in the selected account"}}},"post":{"summary":"Create a project and explicitly adopt a selected runtime footprint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateInput"}}}},"responses":{"201":{"description":"Project and optional capability-scoped runtime foundation"}}}},"/solutions":{"get":{"summary":"List registered solutions","responses":{"200":{"description":"Solution portfolio"}}},"post":{"summary":"Register a solution","responses":{"201":{"description":"Registered solution"}}}},"/solutions/{solutionId}":{"get":{"summary":"Get solution details","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Solution with manifests, bindings, grants, verification, and receipts"}}},"patch":{"summary":"Change solution lifecycle status","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Updated solution"}}}},"/solutions/{solutionId}/manifest":{"get":{"summary":"List immutable manifest versions","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Manifest versions"}}},"post":{"summary":"Create a manifest version","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"201":{"description":"Manifest version"}}}},"/solutions/{solutionId}/environments":{"get":{"summary":"List environment bindings","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Environment bindings"}}},"post":{"summary":"Bind a hosted target","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"201":{"description":"Environment binding"}}}},"/solutions/{solutionId}/verify":{"post":{"summary":"Verify a target","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Verification run and health snapshot"}}}},"/solutions/{solutionId}/deploy":{"post":{"summary":"Register or deploy a target","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"201":{"description":"Deployment receipt"}}}},"/solutions/{solutionId}/rollback":{"post":{"summary":"Rollback to a manifest version","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"201":{"description":"Rollback receipt"}}}},"/solutions/{solutionId}/health":{"get":{"summary":"List health snapshots","parameters":[{"$ref":"#/components/parameters/SolutionId"}],"responses":{"200":{"description":"Health history"}}}},"/developer/service-grants":{"get":{"summary":"List service grants","responses":{"200":{"description":"Service grants without secrets"}}},"post":{"summary":"Create a service grant","responses":{"201":{"description":"Grant and one-time client credentials"}}}},"/developer/token":{"post":{"summary":"Exchange service credentials for a bearer token","security":[],"responses":{"200":{"description":"Scoped service token"}}}},"/developer/events":{"get":{"summary":"List event catalog","responses":{"200":{"description":"Versioned event catalog"}}}},"/developer/data-contract":{"get":{"summary":"Read the public JSON Schema 2020-12 data contract","security":[],"responses":{"200":{"description":"Canonical provider-neutral data schema"}}}},"/developer/data-contract.schema.json":{"get":{"summary":"Relative-ref alias for the canonical data contract JSON Schema","security":[],"responses":{"200":{"description":"Canonical provider-neutral data schema"}}}},"/modules":{"get":{"summary":"List optional module definitions and account assignments","responses":{"200":{"description":"Module catalog and assignments"}}},"post":{"summary":"Enable an optional module","responses":{"201":{"description":"Enabled module assignment"}}}},"/modules/{moduleId}":{"get":{"summary":"Get a module definition and assignment","parameters":[{"$ref":"#/components/parameters/ModuleId"}],"responses":{"200":{"description":"Module definition and assignment"}}},"patch":{"summary":"Update module status or configuration","parameters":[{"$ref":"#/components/parameters/ModuleId"}],"responses":{"200":{"description":"Updated module assignment"}}}},"/communications/messages":{"get":{"summary":"List account or adopted-project communication messages","parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"subjectId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped communication message history"},"409":{"description":"The project has not adopted communications"}}},"post":{"summary":"Queue an idempotent communication message for durable delivery","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient","templateKey","eventType","idempotencyKey"],"properties":{"accountId":{"type":"string"},"projectId":{"type":"string"},"subjectId":{"type":"string"},"recipient":{"type":"string","format":"email"},"channel":{"type":"string","enum":["email"],"default":"email"},"templateKey":{"type":"string"},"locale":{"type":"string","default":"en"},"eventType":{"type":"string"},"idempotencyKey":{"type":"string","minLength":8},"variables":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Existing message reused by idempotency key"},"201":{"description":"Queued communication message"},"409":{"description":"The project has not adopted communications"}}}},"/experience/buyer-library":{"get":{"summary":"Read the customer buyer library, optionally scoped to an adopted project surface","parameters":[{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Storefront, project-scoped catalog, purchases, access, subscriptions, and messages"},"409":{"description":"The project has no selected customer surface"}}}},"/auth/me":{"get":{"summary":"Get the authenticated identity and accessible accounts","responses":{"200":{"description":"Identity profile and account portfolio"}}}},"/auth/session":{"post":{"summary":"Exchange a Firebase ID token for a Povento session cookie","security":[],"responses":{"200":{"description":"Authenticated session"}}},"delete":{"summary":"Clear the current Povento session","security":[],"responses":{"200":{"description":"Signed out"}}}},"/auth/accounts":{"get":{"summary":"List accounts accessible to the identity","responses":{"200":{"description":"Account portfolio"}}},"post":{"summary":"Create an operator account","responses":{"201":{"description":"Account and owner membership"}}}},"/auth/account-selection":{"post":{"summary":"Select an accessible operator account","responses":{"200":{"description":"Selected account"}}},"delete":{"summary":"Clear the selected account","responses":{"200":{"description":"Selection cleared"}}}},"/auth/accounts/{accountId}/members":{"get":{"summary":"List account memberships and invitations","responses":{"200":{"description":"Memberships and invitations"}}},"post":{"summary":"Invite a teammate","responses":{"201":{"description":"Invitation"}}}},"/auth/accounts/{accountId}/members/{principalId}":{"patch":{"summary":"Change a membership role or status","responses":{"200":{"description":"Updated membership"}}}},"/auth/invitations/accept":{"post":{"summary":"Accept a one-time account invitation","security":[],"responses":{"200":{"description":"Accepted invitation and membership"}}}},"/auth/sessions":{"get":{"summary":"List active identity sessions","responses":{"200":{"description":"Session metadata"}}},"delete":{"summary":"Revoke all identity sessions","responses":{"200":{"description":"Revocation timestamp"}}}},"/auth/security":{"get":{"summary":"Read account security policy and events","responses":{"200":{"description":"Security policy and events"}}},"patch":{"summary":"Update account security policy","responses":{"200":{"description":"Updated policy"}}}},"/auth/providers":{"get":{"summary":"List OIDC and SAML providers","responses":{"200":{"description":"Provider registry"}}},"post":{"summary":"Stage an identity provider","responses":{"201":{"description":"Staged provider"}}}},"/auth/passkeys":{"get":{"summary":"List passkey credentials","responses":{"200":{"description":"Passkey credentials"}}},"post":{"summary":"Register a verified WebAuthn credential","responses":{"201":{"description":"Passkey credential"}}},"delete":{"summary":"Revoke a passkey credential","responses":{"200":{"description":"Revoked passkey"}}}},"/auth/scim-tokens":{"get":{"summary":"List SCIM tokens","responses":{"200":{"description":"SCIM tokens without secrets"}}},"post":{"summary":"Create a one-time SCIM token","responses":{"201":{"description":"SCIM token and one-time secret"}}}},"/auth/oauth/apps":{"get":{"summary":"List OAuth applications","responses":{"200":{"description":"OAuth applications"}}},"post":{"summary":"Register an OAuth application","responses":{"201":{"description":"Application and one-time client secret"}}}},"/auth/oauth/register":{"post":{"summary":"Dynamically register a public read-only MCP OAuth client","security":[],"responses":{"201":{"description":"Registered public client ID"},"400":{"description":"Invalid client metadata"}}}},"/auth/oauth/authorize":{"get":{"summary":"Inspect or render an OAuth authorization request","security":[],"responses":{"200":{"description":"Consent details or browser consent page"},"303":{"description":"Redirect to sign-in or client callback"}}},"post":{"summary":"Issue a short-lived authorization code after consent","responses":{"303":{"description":"Authorization callback"}}}},"/auth/oauth/token":{"post":{"summary":"Exchange an authorization code for an access token","security":[],"responses":{"200":{"description":"OAuth access token"}}}},"/auth/project-tokens":{"get":{"summary":"List scoped project tokens","responses":{"200":{"description":"Project tokens without secrets"}}},"post":{"summary":"Create a scoped project token","responses":{"201":{"description":"Project token and one-time secret"}}}},"/runtime/projects/{projectId}/bootstrap":{"get":{"summary":"Read the selected runtime foundation for a project","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Capability-scoped environments, data namespaces, standard surfaces, resources, and health"}}},"post":{"summary":"Provision only the selected project runtime capabilities","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Existing runtime foundation reused idempotently"},"201":{"description":"Created capability-scoped runtime foundation"}}},"patch":{"summary":"Remove one adopted capability after its managed state is exported or removed","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeCapabilityRemovalInput"}}}},"responses":{"200":{"description":"Updated runtime foundation with the selected capability retired"},"409":{"description":"Removal blocked while managed capability state remains"}}}},"/runtime/projects/{projectId}/commerce/catalog":{"get":{"summary":"Read a project-scoped adopted commerce catalog","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Products and offers owned by this project"},"409":{"description":"Commerce is not adopted for this project or environment"}}},"post":{"summary":"Create a project-scoped test commerce product","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"201":{"description":"Created project commerce product"}}}},"/runtime/projects/{projectId}/commerce/offers":{"get":{"summary":"Read offers in a project-scoped adopted commerce catalog","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Project-owned offers"}}},"post":{"summary":"Create a project-scoped test commerce offer","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"201":{"description":"Created project commerce offer"}}}},"/runtime/projects/{projectId}/commerce/checkouts":{"get":{"summary":"List active offers for a project-scoped test checkout","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Active project-owned offers"}}},"post":{"summary":"Create a project-scoped provider-neutral test checkout","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"201":{"description":"Checkout and one-time completion token"}}}},"/runtime/projects/{projectId}/commerce/access":{"get":{"summary":"Decide project-scoped product access","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Provider-neutral entitlement access decision"}}}},"/runtime/projects/{projectId}/data/namespaces":{"get":{"summary":"Read the adopted managed data namespace","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Account-project-environment data namespace"}}},"post":{"summary":"Provision the selected managed data namespace","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Existing data namespace"},"201":{"description":"Created data namespace"}}}},"/runtime/projects/{projectId}/data/schema":{"get":{"summary":"Read the current typed data schema","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Current schema and namespace"}}}},"/runtime/projects/{projectId}/data/schema/validate":{"post":{"summary":"Validate a proposed data schema without applying it","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Schema validation issues and normalized models"}}}},"/runtime/projects/{projectId}/data/schema/plans":{"post":{"summary":"Create a fingerprinted provider-neutral schema plan","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSchemaPlanRequest"}}}},"responses":{"200":{"description":"Read-only schema plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSchemaPlanResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runtime/projects/{projectId}/data/schema/plans/{planId}/apply":{"post":{"summary":"Apply a confirmed schema plan through the durable migration pipeline","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"planId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSchemaPlanApplyRequest"}}}},"responses":{"200":{"description":"Idempotent schema plan replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSchemaPlanApplyResponse"}}}},"201":{"description":"Applied or pending schema plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataSchemaPlanApplyResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/migrations":{"get":{"summary":"List data migrations","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Migration history"}}},"post":{"summary":"Create an approved, version-checked data migration","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"201":{"description":"Applied or pending migration"}}}},"/runtime/projects/{projectId}/data/migration-plans":{"post":{"summary":"Plan a provider-neutral migration without reading or changing source data","description":"Read-only migration planning. Source references are descriptive metadata only; Povento never receives provider credentials or opens a customer provider connection.","x-povento-status":"Available (planning only)","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environment","sourceProvider","destinationProvider","sourceReference","schema"],"additionalProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"sourceProvider":{"type":"string","enum":["d1","firestore","turso","postgres","sqlite","json","csv"]},"destinationProvider":{"type":"string","enum":["firestore","turso"]},"sourceReference":{"type":"string","minLength":1,"maxLength":500},"schema":{"type":"object","required":["entities"],"additionalProperties":true,"properties":{"version":{"type":"string"},"entities":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object"}},"relationships":{"type":"array","items":{"type":"object"}},"features":{"type":"array","items":{"type":"object"}}}},"mappingOverrides":{"type":"array","maxItems":2000,"items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Deterministic migration plan and validation summary"},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runtime/projects/{projectId}/data/migrations/{migrationId}/execute":{"post":{"summary":"Execute a confirmed migration in the bounded relational adapter","description":"Legacy relational execution surface. This route is intentionally provider-gated and does not expose provider URLs or credentials; Firestore-first applications should use the canonical import or schema-plan apply routes.","x-povento-status":"Planned (relational provider only)","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"migrationId","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environment","plan","records","confirmation"],"additionalProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"plan":{"type":"object"},"records":{"type":"array","maxItems":500,"items":{"$ref":"./data-contract.schema.json#/$defs/record"}},"batchSize":{"type":"integer","minimum":1,"maximum":500},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"confirmation":{"type":"object","required":["confirmed"],"properties":{"confirmed":{"const":true}}}}}}}},"responses":{"200":{"description":"Idempotent replay or migration progress"},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Relational provider execution is not configured"}}}},"/runtime/projects/{projectId}/data/imports":{"post":{"summary":"Import bounded records through a durable Povento operation","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataImport"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataImportResponse"}}}},"201":{"description":"Import receipt and records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataImportResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details"},"503":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/verify":{"post":{"summary":"Verify schema, records, checksums, and declared references","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataVerifyResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/health":{"get":{"summary":"Read provider-neutral data health","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Health checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataHealthResponse"}}}},"503":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runtime/projects/{projectId}/data/usage":{"get":{"summary":"Read provider-neutral data usage and limits","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Usage and published limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataUsageResponse"}}}},"503":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/runtime/projects/{projectId}/data/query":{"post":{"summary":"Execute a bounded provider-neutral data query","description":"The body is the scoped Povento query contract; authorization uses the authenticated project, environment, and data capability.","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataQueryRequest"}}}},"responses":{"200":{"description":"Typed page of records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataQueryResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"RFC 9457 problem details"},"409":{"description":"RFC 9457 problem details"},"503":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/mutations":{"post":{"summary":"Execute one idempotent typed data mutation","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataMutationRequest"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataMutationResponse"}}}},"201":{"description":"Committed mutation receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataMutationResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details"},"503":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/transactions":{"post":{"summary":"Execute a bounded atomic idempotent data transaction","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTransactionRequest"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTransactionResponse"}}}},"201":{"description":"Committed transaction receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataTransactionResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details"},"503":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/records":{"get":{"summary":"List typed records in an adopted data model","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"environment","in":"query","required":false,"schema":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"}},{"name":"collection","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page for the same project, environment, and collection.","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Records and scope-bound cursor"},"400":{"description":"Invalid or mismatched cursor"}}},"post":{"summary":"Create a typed data record","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"201":{"description":"Created record"}}}},"/runtime/projects/{projectId}/data/records/{recordId}":{"get":{"summary":"Read a typed data record","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/RecordId"}],"responses":{"200":{"description":"Record","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRecordResponse"}}}},"404":{"description":"RFC 9457 problem details"}}},"patch":{"summary":"Update a typed data record with optimistic concurrency","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/RecordId"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"200":{"description":"Updated record","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRecordResponse"}}}},"409":{"description":"RFC 9457 problem details"}}},"delete":{"summary":"Delete a typed data record with optional optimistic concurrency","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/RecordId"},{"$ref":"#/components/parameters/IfMatch"}],"responses":{"200":{"description":"Deletion result"},"409":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/export":{"post":{"summary":"Create a bounded data export snapshot","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Idempotent export replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExportResponse"}}}},"201":{"description":"Export snapshot with durable receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataExportResponse"}}}}}}},"/runtime/projects/{projectId}/data/exports":{"get":{"summary":"List data export snapshots","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Addressable export history"}}}},"/runtime/projects/{projectId}/data/restore":{"post":{"summary":"Restore an approved local or test data snapshot with a durable receipt","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRestore"}}}},"responses":{"200":{"description":"Idempotent restore replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRestoreResponse"}}}},"201":{"description":"Restore result with pre-restore backup evidence and durable receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataRestoreResponse"}}}},"400":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"RFC 9457 problem details"}}}},"/runtime/projects/{projectId}/data/backups":{"get":{"summary":"List data backup evidence","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Backup evidence"}}}},"/runtime/files":{"get":{"summary":"List adopted project files and quota","parameters":[{"$ref":"#/components/parameters/ProjectIdQuery"},{"name":"environment","in":"query","required":false,"schema":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending_upload","available","quarantined","failed","deleted"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page for the same project, environment, and status filter.","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Scoped file metadata, quota, and cursor"},"400":{"description":"Invalid or mismatched cursor"}}}},"/runtime/files/upload-intents":{"post":{"summary":"Create a short-lived signed upload intent","responses":{"200":{"description":"Idempotently reused upload intent"},"201":{"description":"Pending file metadata and upload intent"}}}},"/runtime/files/{fileId}":{"get":{"summary":"Read file metadata","parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"Scoped file metadata"}}},"patch":{"summary":"Update file label, retention, or metadata","parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"Updated file metadata"}}},"delete":{"summary":"Soft-delete file metadata and content","parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"Deletion result"}}}},"/runtime/files/{fileId}/download-intent":{"post":{"summary":"Create a short-lived signed download intent","parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"File metadata and signed download URL"}}}},"/runtime/files/{fileId}/complete":{"post":{"summary":"Complete a managed-provider upload after direct transfer","parameters":[{"$ref":"#/components/parameters/FileId"},{"$ref":"#/components/parameters/ProjectIdQuery"}],"responses":{"200":{"description":"Available file metadata"}}}},"/runtime/projects/{projectId}/events":{"get":{"summary":"List the adopted project event queue","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"environment","in":"query","required":false,"schema":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","leased","processed","retrying","dead_letter"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page for the same project, environment, and status filter.","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Project-scoped event records, delivery status, and cursor"},"400":{"description":"Invalid or mismatched cursor"}}},"post":{"summary":"Publish an idempotent project event","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"responses":{"200":{"description":"Existing event reused by idempotency key"},"201":{"description":"Queued event"}}}},"/runtime/projects/{projectId}/analytics/events":{"get":{"summary":"List selected project analytics signals","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"environment","in":"query","required":false,"schema":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"}},{"name":"eventName","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned by the previous page for the same project, environment, and event name filter.","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Project- and environment-scoped analytics events, cursor, and usage summary"},"400":{"description":"Invalid or mismatched cursor"},"409":{"description":"Analytics was not adopted for this project or environment"}}},"post":{"summary":"Capture an idempotent selected project analytics signal","parameters":[{"$ref":"#/components/parameters/ProjectId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeAnalyticsPublishInput"}}}},"responses":{"200":{"description":"Existing signal reused by idempotency key"},"201":{"description":"Captured analytics signal"},"409":{"description":"Analytics was not adopted for this project or environment"}}}},"/runtime/projects/{projectId}/events/{eventId}/replay":{"post":{"summary":"Replay a recorded project event","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"$ref":"#/components/parameters/EventId"}],"responses":{"200":{"description":"Event returned to the worker queue"}}}},"/agent/operations":{"post":{"summary":"Reserve or replay a durable agent operation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","fingerprint"],"properties":{"accountId":{"type":"string"},"projectId":{"type":"string"},"environment":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"},"operation":{"type":"string"},"fingerprint":{"type":"string"},"status":{"type":"string","enum":["accepted","running","succeeded","failed","cancelled"],"default":"accepted"},"result":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Exact idempotent replay"},"201":{"description":"Reserved or recorded operation and AgentReceipt"},"409":{"description":"Changed idempotency request"}}}},"/agent/operations/{operationId}":{"get":{"summary":"Read a durable agent operation and receipt","parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Operation and AgentReceipt"}}},"patch":{"summary":"Transition an accepted or running agent operation","parameters":[{"name":"operationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fingerprint","status"],"properties":{"fingerprint":{"type":"string"},"status":{"type":"string","enum":["accepted","running","succeeded","failed","cancelled"]},"result":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Updated or exact replayed AgentReceipt"},"409":{"description":"Changed request or invalid lifecycle transition"}}}},"/api/internal/events/process":{"post":{"summary":"Run the protected runtime event worker","responses":{"200":{"description":"Worker receipts, retries, and dead letters"}}}},"/internal/communications/process":{"get":{"summary":"Run the protected durable communications worker","parameters":[{"name":"accountId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Accepted messages, retrying messages, and terminal failures"},"403":{"description":"Worker secret is invalid or not configured"}}},"post":{"summary":"Run the protected durable communications worker","responses":{"200":{"description":"Accepted messages, retrying messages, and terminal failures"},"403":{"description":"Worker secret is invalid or not configured"}}}},"/runtime/projects/{projectId}/data/models/{model}":{"get":{"summary":"Execute a bounded OData-profile query for one data model","parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"model","in":"path","required":true,"schema":{"type":"string"}},{"name":"$filter","in":"query","schema":{"type":"string"}},{"name":"$select","in":"query","schema":{"type":"string"}},{"name":"$orderby","in":"query","schema":{"type":"string"}},{"name":"$expand","in":"query","schema":{"type":"string"}},{"name":"$top","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"$cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Typed page of records"},"400":{"description":"RFC 9457 problem details"},"403":{"description":"RFC 9457 problem details"},"503":{"description":"RFC 9457 problem details"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer OAuth 2.0/OIDC or scoped Povento workload token. The token is bound to account/project/environment context; never pass provider credentials.","x-povento-permissions":["data:read","data:write","data:schema","data:import","data:export","data:admin"]}},"parameters":{"IfMatch":{"name":"If-Match","in":"header","required":false,"description":"Strong ETag required for optimistic concurrency on updates and deletes.","schema":{"type":"string","pattern":"^\"[0-9]+\"$"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for safe retries and durable receipt replay.","schema":{"type":"string","minLength":8,"maxLength":255}},"SolutionId":{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},"ModuleId":{"name":"moduleId","in":"path","required":true,"schema":{"type":"string"}},"ProjectId":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},"ProjectIdQuery":{"name":"projectId","in":"query","required":true,"schema":{"type":"string"}},"FileId":{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},"RecordId":{"name":"recordId","in":"path","required":true,"schema":{"type":"string"}},"EventId":{"name":"eventId","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"DataQueryRequest":{"type":"object","required":["model"],"unevaluatedProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"model":{"$ref":"./data-contract.schema.json#/$defs/identifier"},"select":{"type":"array","maxItems":50,"items":{"$ref":"./data-contract.schema.json#/$defs/identifier"}},"where":{"type":"array","maxItems":20,"items":{"$ref":"./data-contract.schema.json#/$defs/where"}},"orderBy":{"type":"array","maxItems":5,"items":{"$ref":"./data-contract.schema.json#/$defs/order"}},"include":{"type":"array","maxItems":5,"items":{"$ref":"./data-contract.schema.json#/$defs/include"}},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"cursor":{"type":"string","maxLength":2000}}},"DataMutationRequest":{"type":"object","required":["mutation"],"unevaluatedProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"mutation":{"$ref":"./data-contract.schema.json#/$defs/mutation"}}},"DataTransactionRequest":{"type":"object","required":["transaction"],"unevaluatedProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"transaction":{"$ref":"./data-contract.schema.json#/$defs/transaction"}}},"DataIdentifier":{"$ref":"./data-contract.schema.json#/$defs/identifier"},"DataEnvironment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"DataQuery":{"$ref":"./data-contract.schema.json#/$defs/query"},"DataMutation":{"$ref":"./data-contract.schema.json#/$defs/mutation"},"DataTransaction":{"$ref":"./data-contract.schema.json#/$defs/transaction"},"DataSchemaPlan":{"$ref":"./data-contract.schema.json#/$defs/schemaPlan"},"DataSchemaPlanRequest":{"type":"object","required":["models"],"unevaluatedProperties":false,"properties":{"accountId":{"type":"string"},"environment":{"$ref":"./data-contract.schema.json#/$defs/environment"},"name":{"type":"string","minLength":1,"maxLength":160},"models":{"type":"array","maxItems":50,"items":{"$ref":"./data-contract.schema.json#/$defs/model"}}}},"DataSchemaPlanResponse":{"type":"object","required":["namespace","plan"],"additionalProperties":false,"properties":{"namespace":{"$ref":"./data-contract.schema.json#/$defs/namespace"},"plan":{"$ref":"./data-contract.schema.json#/$defs/schemaPlan"}}},"DataSchemaPlanApplyRequest":{"type":"object","required":["plan","confirmation"],"unevaluatedProperties":false,"properties":{"plan":{"$ref":"./data-contract.schema.json#/$defs/schemaPlan"},"confirmation":{"type":"object","required":["confirmed"],"additionalProperties":false,"properties":{"confirmed":{"const":true}}}}},"DataSchemaPlanApplyResponse":{"type":"object","required":["plan","namespace","migration","schema","receipt"],"additionalProperties":false,"properties":{"plan":{"$ref":"./data-contract.schema.json#/$defs/schemaPlan"},"namespace":{"$ref":"./data-contract.schema.json#/$defs/namespace"},"migration":{"type":"object"},"schema":{"anyOf":[{"type":"object"},{"type":"null"}]},"receipt":{"$ref":"./data-contract.schema.json#/$defs/receipt"}}},"DataImport":{"$ref":"./data-contract.schema.json#/$defs/import"},"DataRestore":{"$ref":"./data-contract.schema.json#/$defs/restore"},"DataRecord":{"$ref":"./data-contract.schema.json#/$defs/record"},"DataRecordResponse":{"$ref":"./data-contract.schema.json#/$defs/recordResponse"},"DataReceipt":{"$ref":"./data-contract.schema.json#/$defs/receipt"},"DataQueryResponse":{"$ref":"./data-contract.schema.json#/$defs/queryResponse"},"DataMutationResponse":{"$ref":"./data-contract.schema.json#/$defs/mutationResponse"},"DataTransactionResponse":{"$ref":"./data-contract.schema.json#/$defs/transactionResponse"},"DataImportResponse":{"$ref":"./data-contract.schema.json#/$defs/importResponse"},"DataExportResponse":{"$ref":"./data-contract.schema.json#/$defs/exportResponse"},"DataRestoreResponse":{"$ref":"./data-contract.schema.json#/$defs/restoreResponse"},"DataVerifyResponse":{"$ref":"./data-contract.schema.json#/$defs/verifyResponse"},"DataHealthResponse":{"$ref":"./data-contract.schema.json#/$defs/healthResponse"},"DataUsageResponse":{"$ref":"./data-contract.schema.json#/$defs/usageResponse"},"Problem":{"$ref":"./data-contract.schema.json#/$defs/problem"},"RuntimeCapabilityRemovalInput":{"type":"object","required":["capability","confirmed"],"properties":{"accountId":{"type":"string"},"capability":{"type":"string","enum":["identity","data","files","commerce","surfaces","events","communications","analytics","deployment","operations"]},"confirmed":{"type":"boolean","const":true},"expectedUpdatedAt":{"type":"string","format":"date-time"}}},"RuntimeAnalyticsPublishInput":{"type":"object","required":["eventName","idempotencyKey"],"properties":{"accountId":{"type":"string"},"environment":{"type":"string","enum":["local","test","preview","staging","production"],"default":"local"},"eventName":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9._-]*$"},"schemaVersion":{"type":"integer","minimum":1,"default":1},"occurredAt":{"type":"string","format":"date-time"},"causationId":{"type":"string"},"properties":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string","minLength":8,"maxLength":255}}},"RuntimeAnalyticsEvent":{"type":"object","required":["id","accountId","projectId","environment","eventName","schemaVersion","actor","occurredAt","receivedAt","correlationId","properties","idempotencyKey"],"properties":{"id":{"type":"string"},"accountId":{"type":"string"},"projectId":{"type":"string"},"environment":{"type":"string","enum":["local","test","preview","staging","production"]},"eventName":{"type":"string"},"schemaVersion":{"type":"integer"},"actor":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["user","service","system","demo"]},"id":{"type":"string"}}},"occurredAt":{"type":"string","format":"date-time"},"receivedAt":{"type":"string","format":"date-time"},"correlationId":{"type":"string"},"causationId":{"type":"string"},"properties":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string"}}},"RuntimeAnalyticsSummary":{"type":"object","required":["projectId","environment","recordedCount","eventTypeCount","activeActorCount","meteredEventCount","breakdown"],"properties":{"projectId":{"type":"string"},"environment":{"type":"string","enum":["local","test","preview","staging","production"]},"recordedCount":{"type":"integer","minimum":0},"eventTypeCount":{"type":"integer","minimum":0},"activeActorCount":{"type":"integer","minimum":0},"meteredEventCount":{"type":"integer","minimum":0},"firstEventAt":{"type":"string","format":"date-time"},"latestEventAt":{"type":"string","format":"date-time"},"breakdown":{"type":"array","items":{"type":"object","required":["eventName","count"],"properties":{"eventName":{"type":"string"},"count":{"type":"integer","minimum":0}}}}}},"ProjectCreateInput":{"type":"object","required":["name","type"],"properties":{"accountId":{"type":"string"},"name":{"type":"string","minLength":2},"type":{"type":"string","minLength":2},"description":{"type":"string"},"domain":{"type":"string"},"runtime":{"type":"object","required":["capabilities"],"properties":{"capabilities":{"type":"array","items":{"type":"string","enum":["identity","data","files","commerce","surfaces","events","communications","analytics","deployment","operations"]}},"environments":{"type":"array","items":{"type":"string","enum":["local","test","preview","staging","production"]}}}}}}}}}