{ "openapi": "3.1.0", "info": { "title": "MiniCenter Contract Spine", "version": "0.1.0" }, "servers": [{"url": "/api/v1"}], "paths": { "/health": { "get": { "operationId": "health", "responses": { "200": { "description": "Runtime and contract identity", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/Health"} } } } } } }, "/project-client": { "get": { "operationId": "projectClient", "summary": "Inspect the authenticated Project Client", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read; retries do not change Project Client state.", "x-sdk-methods": { "TypeScript": { "method": "MiniCenterClient.request", "path": "/docs/developer-tooling/sdk/typescript/first-request" }, "Python": { "method": "Client.request", "path": "/docs/developer-tooling/sdk/python/first-request" }, "PHP": { "method": "Client::request", "path": "/docs/developer-tooling/sdk/php/first-request" }, "Go": { "method": "Client.Do", "path": "/docs/developer-tooling/sdk/go/first-request" }, "CLI": { "method": "minicenter request", "path": "/docs/developer-tooling/sdk/cli/first-request" } }, "security": [{"projectCredential": ["clients:read"]}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "responses": { "200": { "description": "Authenticated Project Client", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": {"$ref": "#/components/schemas/ProjectClient"} } }, "example": { "data": { "id": "30000000-0000-4000-8000-000000000003", "name": "Sandbox Storefront", "environment": "sandbox", "scopes": ["clients:read"] } } } } }, "401": { "description": "Invalid or revoked Project Credential", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "403": { "description": "Project Credential lacks the required scope", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "429": {"$ref": "#/components/responses/QuotaExceeded"} } } }, "/project-audits": { "post": { "operationId": "submitProjectAudit", "summary": "Submit one constrained Project Audit fact", "description": "The authenticated Project Credential selects the Project Client. The contract accepts only opaque actor and resource references plus a bounded action and outcome; it never accepts business or secret payloads.", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Repeating the identical fact returns the same Project Audit ID; reusing the key for different facts is rejected.", "security": [{"projectCredential": ["audit:write"]}], "parameters": [ {"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ProjectAuditFact"}, "example": { "actor_id": "actor:38000000-0000-4000-8000-000000000010", "action": "project.membership.changed", "resource_type": "ProjectMembership", "resource_id": "membership:38000000-0000-4000-8000-000000000011", "outcome": "succeeded" } }}}, "responses": { "201": {"description": "Project Audit fact accepted or identically replayed", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ProjectAuditEnvelope"}, "example": {"data": {"id": "38000000-0000-4000-8000-000000000012"}} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/QuotaExceeded"} } } }, "/identity-migration-transactions": { "post": { "operationId": "createIdentityMigrationTransaction", "summary": "Create an Identity Migration Transaction", "description": "The Project Backend MUST create this transaction only after recently authenticating the project-scoped legacy subject, including the project's own additional factor when its policy requires one. MiniCenter never receives that credential or factor.", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key; retry the identical request after an uncertain response.", "security": [{"projectCredential": ["identity-migrations:write"]}], "parameters": [{"$ref": "#/components/parameters/WriteIdempotencyKey"}], "requestBody": {"required": true, "content": {"application/json": { "schema": {"type": "object", "additionalProperties": false, "required": ["project_client_id", "legacy_subject", "email", "locale", "correlation_id", "expires_at"], "properties": { "project_client_id": {"type": "string", "format": "uuid"}, "legacy_subject": {"type": "string", "maxLength": 255}, "email": {"type": "string", "format": "email", "maxLength": 255}, "locale": {"type": "string", "maxLength": 20}, "correlation_id": {"type": "string", "format": "uuid"}, "expires_at": {"type": "string", "format": "date-time"} }}, "example": {"project_client_id": "30000000-0000-4000-8000-000000000003", "legacy_subject": "legacy-42", "email": "ada@example.test", "locale": "zh-TW", "correlation_id": "10000000-0000-4000-8000-000000000196", "expires_at": "2026-08-02T10:10:00Z"} }}}, "responses": { "201": {"description": "Short-lived migration flow; flow_token is creation-only and must be delivered to the MiniCenter registration-or-linking flow", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatedIdentityMigrationTransactionEnvelope"}, "example": {"data": {"id": "60000000-0000-4000-8000-000000000196", "project_client_id": "30000000-0000-4000-8000-000000000003", "legacy_subject": "legacy-42", "email": "ada@example.test", "locale": "zh-TW", "correlation_id": "10000000-0000-4000-8000-000000000196", "expires_at": "2026-08-02T10:10:00Z", "status": "pending", "account_id": null, "flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/identity-migration-transactions/{transactionId}": { "get": { "operationId": "getIdentityMigrationTransaction", "summary": "Inspect an Identity Migration Transaction", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe client-scoped read.", "security": [{"projectCredential": ["identity-migrations:write"]}], "parameters": [{"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": { "200": {"description": "Current transaction state", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IdentityMigrationTransactionEnvelope"}, "example": {"data": {"id": "60000000-0000-4000-8000-000000000196", "project_client_id": "30000000-0000-4000-8000-000000000003", "legacy_subject": "legacy-42", "email": "ada@example.test", "locale": "zh-TW", "correlation_id": "10000000-0000-4000-8000-000000000196", "expires_at": "2026-08-02T10:10:00Z", "status": "link_pending", "account_id": "20000000-0000-4000-8000-000000000001"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "Transaction is absent from this Project Client"} } } }, "/identity-migration-transactions/{transactionId}/hosted-continuations": { "post": { "operationId": "createHostedIdentityMigrationContinuation", "summary": "Create a browser-safe hosted Identity Migration handoff", "description": "The Project Backend exchanges the creation-only flow_token server-to-server. It then submits only the returned continuation_id and continuation_token in a direct form POST to /identity-migration/continue. Neither token belongs in a URL, log, analytics event, browser storage, or third-party origin.", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key; retry the identical request after an uncertain response to recover the same one-browser continuation.", "security": [{"projectCredential": ["identity-migrations:write"]}], "parameters": [ {"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": {"type": "object", "additionalProperties": false, "required": ["flow_token", "return_uri", "state"], "properties": { "flow_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "return_uri": {"type": "string", "format": "uri", "maxLength": 2048}, "state": {"type": "string", "maxLength": 2048} }}, "example": { "flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "return_uri": "https://project.example.test/migration/callback", "state": "opaque-project-state" } }}}, "responses": { "201": {"description": "Creation-only browser handoff. Submit both fields in a form POST to /identity-migration/continue.", "content": {"application/json": { "schema": {"type": "object", "additionalProperties": false, "required": ["data"], "properties": {"data": { "type": "object", "additionalProperties": false, "required": ["id", "continuation_token", "expires_at"], "properties": { "id": {"type": "string", "format": "uuid"}, "continuation_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "expires_at": {"type": "string", "format": "date-time"} } }}}, "example": {"data": { "id": "61000000-0000-4000-8000-000000000229", "continuation_token": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "expires_at": "2026-08-05T10:10:00Z" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/identity-migration-transactions/{transactionId}/link": { "post": { "operationId": "linkIdentityMigrationTransaction", "summary": "Link an authenticated Platform Account", "tags": ["identity-trust"], "description": "Requires a recently authenticated Platform Session and an email Login Identifier verified after this migration transaction was created. A newly registered and verified account uses this same operation.", "x-documentation": true, "x-stability": "stable", "x-idempotency": "Single-use; retry by the same authenticated Platform Account returns the established link.", "security": [{"platformSession": []}], "parameters": [{"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["flow_token"], "properties": {"flow_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}}, "example": {"flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}, "responses": { "200": {"description": "Authenticated link awaits Project Backend confirmation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IdentityMigrationTransactionEnvelope"}, "example": {"data": {"id": "60000000-0000-4000-8000-000000000196", "project_client_id": "30000000-0000-4000-8000-000000000003", "legacy_subject": "legacy-42", "email": "ada@example.test", "locale": "zh-TW", "correlation_id": "10000000-0000-4000-8000-000000000196", "expires_at": "2026-08-02T10:10:00Z", "status": "link_pending", "account_id": "20000000-0000-4000-8000-000000000001"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/identity-migration-transactions/{transactionId}/confirm-link": { "post": { "operationId": "confirmIdentityMigrationLink", "summary": "Confirm the durable Project Backend account link", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe to retry after the Project Backend durably records the Account ID link.", "security": [{"projectCredential": ["identity-migrations:write"]}], "parameters": [{"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": { "200": {"description": "Completed Identity Migration", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IdentityMigrationTransactionEnvelope"}, "example": {"data": {"id": "60000000-0000-4000-8000-000000000196", "project_client_id": "30000000-0000-4000-8000-000000000003", "legacy_subject": "legacy-42", "email": "ada@example.test", "locale": "zh-TW", "correlation_id": "10000000-0000-4000-8000-000000000196", "expires_at": "2026-08-02T10:10:00Z", "status": "completed", "account_id": "20000000-0000-4000-8000-000000000001"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/identity-migration-transactions/{transactionId}/email-verification": { "post": { "operationId": "requestIdentityMigrationEmailVerification", "summary": "Request fresh email verification for an existing Platform Account", "description": "Requires a recently authenticated Platform Session that already owns the asserted email. MiniCenter emails a short-lived, single-use verification link and records evidence only for this migration transaction.", "tags": ["identity-trust"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "A repeat request invalidates the previous verification link and sends a new short-lived link.", "security": [{"platformSession": []}], "parameters": [{"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["flow_token"], "properties": {"flow_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"}}}, "example": {"flow_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}}, "responses": { "202": {"description": "Verification email accepted", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "required": ["data"], "properties": {"data": {"type": "object", "additionalProperties": false, "required": ["status"], "properties": {"status": {"const": "verification_pending"}}}}}, "example": {"data": {"status": "verification_pending"}}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/identity-migration-transactions/{transactionId}/verify-email/{token}": { "get": { "operationId": "verifyIdentityMigrationEmail", "summary": "Consume a migration email verification link", "tags": ["identity-trust"], "x-documentation": false, "x-stability": "stable", "security": [], "parameters": [ {"name": "transactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "token", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[a-f0-9]{64}$"}} ], "responses": {"200": {"description": "Email verified"}, "422": {"$ref": "#/components/responses/ValidationError"}} } }, "/file-objects/upload-grants": { "post": { "operationId": "createFileUploadGrant", "summary": "Create a File Object upload grant", "tags": ["files-media"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires a unique Idempotency-Key. The upload token is returned only once; reuse is rejected.", "security": [{"projectCredential": ["files:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": {"example": { "expected_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expected_content_type": "image/png", "maximum_bytes": 1048576 }, "schema": { "type": "object", "additionalProperties": false, "required": ["expected_sha256", "expected_content_type", "maximum_bytes"], "properties": { "expected_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "expected_content_type": { "type": "string", "maxLength": 120, "enum": ["application/pdf", "image/gif", "image/jpeg", "image/png", "text/plain"] }, "maximum_bytes": {"type": "integer", "minimum": 1, "maximum": 1073741824} } }}}}, "responses": { "200": {"description": "Single-use upload grant", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/FileUploadGrantEnvelope"}, "example": {"data": { "file_object_id": "50000000-0000-4000-8000-000000000005", "upload_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expires_at": "2026-07-30T10:00:00Z" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/file-uploads/{uploadToken}": { "put": { "operationId": "uploadGrantedFile", "summary": "Upload bytes with a single-use grant", "tags": ["files-media"], "security": [], "x-documentation": true, "x-stability": "stable", "x-idempotency": "The upload token is single-use; obtain a new grant after an uncertain upload.", "parameters": [{"name": "uploadToken", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }}], "requestBody": {"required": true, "content": { "application/octet-stream": { "schema": {"type": "string", "format": "binary"}, "example": "" }, "text/plain": {"schema": {"type": "string", "format": "binary"}}, "image/jpeg": {"schema": {"type": "string", "format": "binary"}}, "image/gif": {"schema": {"type": "string", "format": "binary"}}, "image/png": {"schema": {"type": "string", "format": "binary"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}} }}, "responses": { "200": {"description": "Uploaded quarantined File Object", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/FileUploadEnvelope"}, "example": {"data": {"file_object_id": "50000000-0000-4000-8000-000000000005"}} }}}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/file-objects/{fileObjectId}/complete": { "post": { "operationId": "completeFileUpload", "summary": "Complete and classify a quarantined File Object", "tags": ["files-media"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe to retry for the same File Object; completion returns its current classification.", "security": [{"projectCredential": ["files:write"]}], "parameters": [ {"name": "fileObjectId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/CorrelationId"} ], "responses": { "200": {"description": "File safety classification", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/FileObjectEnvelope"}, "example": {"data": { "id": "50000000-0000-4000-8000-000000000005", "status": "available", "rejection_reason": null }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/file-objects/{fileObjectId}/download-grants": { "post": { "operationId": "createPrivateFileDownloadGrant", "summary": "Create a short-lived authorized private download grant", "tags": ["files-media"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Retry with the same Idempotency-Key for the same File Object after a lost response.", "security": [{"projectCredential": ["files:read"]}], "parameters": [ {"name": "fileObjectId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "responses": { "200": {"description": "Short-lived download grant", "content": {"application/json": {"schema": { "type": "object", "required": ["data"], "properties": {"data": {"type": "object", "required": ["grant_id", "download_url", "expires_at"], "properties": { "grant_id": {"type": "string", "format": "uuid"}, "download_url": {"type": "string", "format": "uri"}, "expires_at": {"type": "string", "format": "date-time"} }}} }, "example": {"data": { "grant_id": "50000000-0000-4000-8000-000000000006", "download_url": "https://storage.example.test/private-download", "expires_at": "2026-08-09T13:00:00Z" }}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/file-objects/{fileObjectId}/public-assets": { "post": { "operationId": "publishFilePublicAsset", "summary": "Publish an available image through an approved metadata-stripping preset", "tags": ["files-media"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Retry the same File Object and approved preset with the same Idempotency-Key after a lost response.", "security": [{"projectCredential": ["files:write"]}], "parameters": [ {"name": "fileObjectId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": {"example": { "image_preset_id": "50000000-0000-4000-8000-000000000008" }, "schema": { "type": "object", "additionalProperties": false, "required": ["image_preset_id"], "properties": {"image_preset_id": {"type": "string", "format": "uuid"}} }}}}, "responses": { "200": {"description": "Published Public Asset", "content": {"application/json": {"schema": { "type": "object", "required": ["data"], "properties": {"data": {"type": "object", "required": ["id", "version", "url", "sha256"], "properties": { "id": {"type": "string", "format": "uuid"}, "version": {"type": "integer", "minimum": 1}, "url": {"type": "string", "format": "uri"}, "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"} }}} }, "example": {"data": { "id": "50000000-0000-4000-8000-000000000007", "version": 1, "url": "https://cdn.example.test/public/lawyer-profile.png", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/domain-events": { "post": { "operationId": "publishDomainEvent", "security": [{"projectCredential": ["events:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["type", "schema_version", "data"], "dependentRequired": { "stream_id": ["sequence"], "sequence": ["stream_id"] }, "properties": { "type": {"type": "string", "maxLength": 120, "pattern": "^[a-z][a-z0-9_.-]+$"}, "schema_version": {"type": "integer", "minimum": 1, "maximum": 65535}, "data": {"type": "object"}, "stream_id": {"type": ["string", "null"], "maxLength": 180}, "sequence": {"type": ["integer", "null"], "minimum": 1}, "occurred_at": {"type": ["string", "null"], "format": "date-time"} } }}}}, "responses": { "200": {"description": "Idempotently published Domain Event", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/DomainEventEnvelope"} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/notification-intents": { "post": { "operationId": "createNotificationIntent", "summary": "Create a Notification Intent", "tags": ["notifications"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Retry the same Notification Intent with the same key and unchanged body.", "security": [{"projectCredential": ["notifications:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["sender_profile_id", "template_key", "locale", "endpoint_id", "variables"], "properties": { "sender_profile_id": {"type": "string", "format": "uuid"}, "template_key": {"type": "string", "maxLength": 120}, "locale": {"type": "string", "maxLength": 20}, "endpoint_id": {"type": "string", "format": "uuid"}, "variables": { "type": "object", "maxProperties": 50, "additionalProperties": { "oneOf": [ {"type": "string", "maxLength": 5000}, {"type": "integer"}, {"type": "number"} ] } }, "marketing_purpose": {"type": ["string", "null"], "maxLength": 120} } }, "example": { "sender_profile_id": "81000000-0000-4000-8000-000000000001", "template_key": "sandbox-welcome", "locale": "zh-TW", "endpoint_id": "82000000-0000-4000-8000-000000000001", "variables": {"display_name": "Sandbox user"} } }}}, "responses": { "200": {"description": "Durable Notification Intent", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/NotificationIntentEnvelope"}, "example": {"data": { "intent_id": "84000000-0000-4000-8000-000000000001", "delivery_id": "85000000-0000-4000-8000-000000000001", "status": "pending" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/channel-notification-intents": { "post": { "operationId": "createChannelNotificationIntent", "summary": "Create an FCM, APNs, LINE, or Web Push Notification Intent", "tags": ["notifications"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Retry the same Notification Intent with the same key and unchanged body.", "security": [{"projectCredential": ["notifications:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["sender_profile_id", "endpoint_id", "template_key", "locale", "purpose", "variables"], "properties": { "sender_profile_id": {"type": "string", "format": "uuid"}, "endpoint_id": {"type": "string", "format": "uuid"}, "template_key": {"type": "string", "maxLength": 120}, "locale": {"type": "string", "maxLength": 20}, "purpose": {"type": "string", "maxLength": 120}, "variables": { "type": "object", "maxProperties": 50, "additionalProperties": { "oneOf": [ {"type": "string", "maxLength": 5000}, {"type": "integer"}, {"type": "number"} ] } } } }, "example": { "sender_profile_id": "81000000-0000-4000-8000-000000000002", "endpoint_id": "82000000-0000-4000-8000-000000000002", "template_key": "sandbox-alert", "locale": "zh-TW", "purpose": "service-alerts", "variables": {"display_name": "Sandbox user"} } }}}, "responses": { "200": {"description": "Durable channel Notification Intent", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/NotificationIntentEnvelope"}, "example": {"data": { "intent_id": "84000000-0000-4000-8000-000000000002", "delivery_id": "85000000-0000-4000-8000-000000000002", "status": "pending" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/notification-deliveries/{deliveryId}": { "get": { "operationId": "getNotificationDelivery", "summary": "Get a Notification Delivery outcome", "tags": ["notifications"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read; repeated requests do not change the Delivery.", "security": [{"projectCredential": ["notifications:write"]}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "deliveryId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Current email or channel Delivery outcome", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/NotificationDeliveryEnvelope"}, "example": {"data": { "id": "85000000-0000-4000-8000-000000000002", "channel": "fcm", "status": "sent", "attempts": 1, "provider_status": "accepted", "last_error_code": null }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/scheduled-operations": { "post": { "operationId": "registerScheduledOperation", "summary": "Register a scheduled operation endpoint", "tags": ["jobs-scheduling"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Reuse the key only with the same endpoint, secret, and retry policy.", "security": [{"projectCredential": ["schedules:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["name", "url", "secret"], "properties": { "name": {"type": "string", "maxLength": 120, "pattern": "^[a-z][a-z0-9_.-]+$"}, "url": {"type": "string", "format": "uri", "maxLength": 2048}, "secret": {"type": "string", "minLength": 32, "maxLength": 255}, "max_attempts": {"type": "integer", "minimum": 1, "maximum": 100, "default": 5} } }, "example": { "name": "reports.refresh", "url": "https://backend.example.com/invocations", "secret": "replace-with-at-least-32-random-characters", "max_attempts": 5 } }}}, "responses": { "200": {"description": "Registered operation", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/RegisteredScheduledOperationEnvelope"}, "example": {"data": {"id": "86000000-0000-4000-8000-000000000001"}} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/invocation-schedules": { "post": { "operationId": "scheduleInvocation", "summary": "Schedule a registered operation", "tags": ["jobs-scheduling"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Reuse the key only with the same operation, arguments, run time, and interval.", "security": [{"projectCredential": ["schedules:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["registered_operation_id", "arguments", "run_at"], "properties": { "registered_operation_id": {"type": "string", "format": "uuid"}, "arguments": {"type": "object", "maxProperties": 50}, "run_at": {"type": "string", "format": "date-time"}, "interval_seconds": {"type": ["integer", "null"], "minimum": 60, "maximum": 2678400} } }, "example": { "registered_operation_id": "86000000-0000-4000-8000-000000000001", "arguments": {"report_id": "weekly-sales"}, "run_at": "2026-08-01T01:00:00Z", "interval_seconds": 86400 } }}}, "responses": { "200": {"description": "Created schedule and first invocation", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/InvocationScheduleCreatedEnvelope"}, "example": {"data": { "schedule_id": "87000000-0000-4000-8000-000000000001", "invocation_id": "88000000-0000-4000-8000-000000000001" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/invocation-schedules/{scheduleId}": { "get": { "operationId": "getInvocationSchedule", "summary": "Get an invocation schedule and its runs", "tags": ["jobs-scheduling"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read; repeated requests do not change the schedule.", "security": [{"projectCredential": ["schedules:write"]}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "scheduleId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Schedule and invocation history", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/InvocationScheduleEnvelope"}, "example": {"data": { "id": "87000000-0000-4000-8000-000000000001", "status": "active", "recurring": true, "quota": null, "invocations": [{ "id": "88000000-0000-4000-8000-000000000001", "scheduled_for": "2026-08-01 01:00:00", "status": "pending", "attempts": 0, "last_error_code": null }] }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } }, "delete": { "operationId": "cancelInvocationSchedule", "summary": "Cancel an invocation schedule", "tags": ["jobs-scheduling"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Cancellation is idempotent; repeated requests return the cancelled schedule.", "security": [{"projectCredential": ["schedules:write"]}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "scheduleId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Cancelled schedule", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/InvocationScheduleEnvelope"}, "example": {"data": { "id": "87000000-0000-4000-8000-000000000001", "status": "cancelled", "recurring": true, "quota": null, "invocations": [{ "id": "88000000-0000-4000-8000-000000000001", "scheduled_for": "2026-08-01 01:00:00", "status": "cancelled", "attempts": 0, "last_error_code": "schedule_cancelled" }] }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/scheduled-invocations/{invocationId}": { "get": { "operationId": "getScheduledInvocation", "summary": "Get a scheduled invocation outcome", "tags": ["jobs-scheduling"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read; repeated requests do not change the invocation.", "security": [{"projectCredential": ["schedules:write"]}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "invocationId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Current invocation outcome", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ScheduledInvocationEnvelope"}, "example": {"data": { "id": "88000000-0000-4000-8000-000000000001", "status": "retry", "attempts": 1, "last_error_code": "http_503" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/realtime-grants": { "post": { "operationId": "issueRealtimeGrant", "summary": "Issue a short-lived Realtime grant", "tags": ["realtime"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Each request issues a new short-lived grant. Request a replacement when reconnecting near or after expiry.", "security": [{"projectCredential": ["realtime:connect"]}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["subject", "channels", "capabilities"], "properties": { "subject": {"type": "string", "maxLength": 180}, "channels": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": {"type": "string", "maxLength": 180} }, "capabilities": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": {"type": "string", "enum": ["subscribe", "publish"]} } } }, "example": { "subject": "platform-account:30000000-0000-4000-8000-000000000003", "channels": ["notifications:30000000-0000-4000-8000-000000000003"], "capabilities": ["subscribe"] } } } }, "responses": { "200": { "description": "Short-lived client-scoped realtime grant", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": ["token", "expires_at"], "properties": { "token": {"type": "string"}, "expires_at": {"type": "string", "format": "date-time"} } } } }, "example": {"data": { "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gifQ.example.signature", "expires_at": "2026-08-01T01:05:00Z" }} } } }, "401": { "description": "Invalid or revoked Project Credential", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "403": { "description": "Project Credential lacks realtime grant scope", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "422": { "description": "Invalid subject, channel, or capability", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": { "code": "validation_failed", "message": "The given data was invalid.", "retryable": false, "correlation_id": "89000000-0000-4000-8000-000000000001", "details": {"channels": ["At least one channel is required."]} }} } } } } } }, "/privacy-requests": { "post": { "operationId": "createPrivacyRequest", "summary": "Create a verified Privacy Request", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Creating a request is not idempotent. Submit once after recent authentication, then retain the returned request id.", "x-authentication-note": "Requires recent authentication.", "security": [{"platformSession": []}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["type"], "properties": { "type": {"type": "string", "enum": ["access", "export", "correction", "deletion", "stop_processing"]}, "details": {"type": ["string", "null"], "maxLength": 4000} } }, "example": {"type": "export", "details": "Please provide my MiniCenter-held data."} }}}, "responses": { "202": {"description": "Verified Privacy Request accepted", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/PrivacyRequestEnvelope"}, "example": {"data": { "id": "8b000000-0000-4000-8000-000000000001", "platform_account_id": "30000000-0000-4000-8000-000000000003", "type": "export", "status": "verified", "acknowledgement_due_at": "2026-08-08T01:00:00Z", "response_due_at": "2026-08-31T01:00:00Z", "progress_summary": null, "progress_at": null, "extended_response_due_at": null, "closed_unverified_at": null, "fallback_contact": "legal@otus.tw", "legal_holds": [], "required_retention": [] }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/privacy-requests/{privacyRequestId}": { "get": { "operationId": "getPrivacyRequest", "summary": "Get the authenticated account's Privacy Request", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe account-scoped read; repeated requests do not change the Privacy Request.", "security": [{"platformSession": []}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "privacyRequestId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Current Privacy Request lifecycle state", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/PrivacyRequestEnvelope"}, "example": {"data": { "id": "8b000000-0000-4000-8000-000000000001", "platform_account_id": "30000000-0000-4000-8000-000000000003", "type": "export", "status": "in_progress", "acknowledgement_due_at": "2026-08-08T01:00:00Z", "response_due_at": "2026-08-31T01:00:00Z", "progress_summary": "Preparing export", "progress_at": "2026-08-02T01:00:00Z", "extended_response_due_at": null, "closed_unverified_at": null, "fallback_contact": "legal@otus.tw", "legal_holds": [], "required_retention": [] }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/privacy-requests/{privacyRequestId}/export": { "post": { "operationId": "createPrivacyExport", "summary": "Create a single-use Privacy Export", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "The export action reuses the valid export for the same request and does not create duplicate archives.", "x-authentication-note": "Requires recent authentication.", "security": [{"platformSession": []}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "privacyRequestId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "201": {"description": "Single-use export is ready", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/PrivacyExportEnvelope"}, "example": {"data": { "id": "8c000000-0000-4000-8000-000000000001", "download_path": "/api/v1/privacy-exports/{single-use-token}", "expires_at": "2026-08-08T01:00:00Z" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/privacy-exports/{token}": { "get": { "operationId": "downloadPrivacyExport", "summary": "Download a single-use Privacy Export", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "The successful download consumes the token; retrying that token returns 410 Gone.", "x-authentication-note": "Requires recent authentication.", "security": [{"platformSession": []}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "token", "in": "path", "required": true, "schema": {"type": "string"}} ], "responses": { "200": {"description": "Private no-store ZIP export", "headers": { "Cache-Control": {"schema": {"type": "string"}, "description": "Always no-store, private"} }, "content": {"application/zip": { "schema": {"type": "string", "format": "binary"}, "example": "binary ZIP content" }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "No ready Privacy Export exists for this account and token"}, "410": {"description": "The single-use export is expired or already consumed"} } } }, "/privacy-requests/{privacyRequestId}/correction": { "post": { "operationId": "applyPrivacyCorrection", "summary": "Apply a Privacy Request correction", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Reusing the correlation identifier with the same request replays the result; changing the payload is rejected.", "x-authentication-note": "Requires recent authentication.", "security": [{"platformSession": []}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "privacyRequestId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "requestBody": {"required": true, "content": {"application/json": { "schema": {"oneOf": [ { "type": "object", "additionalProperties": false, "required": ["target", "value"], "properties": { "target": {"type": "string", "enum": ["platform_account.preferred_locale"]}, "value": {"type": "string", "enum": ["zh-TW", "en"]} } }, { "type": "object", "additionalProperties": false, "required": ["target", "reference_id", "statement"], "properties": { "target": {"type": "string", "enum": ["terms_acceptance", "privacy_notice_acknowledgement", "platform_session", "platform_audit"]}, "reference_id": {"type": "string", "maxLength": 180}, "statement": {"type": "string", "maxLength": 4000} } } ]}, "example": {"target": "platform_account.preferred_locale", "value": "zh-TW"} }}}, "responses": { "200": {"description": "Correction applied or recorded as an append-only correction", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/PrivacyCorrectionEnvelope"}, "example": {"data": {"outcome": "corrected", "evidence": { "type": "direct_change", "reference": "8d000000-0000-4000-8000-000000000001" }}} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/privacy-requests/{privacyRequestId}/stop-processing": { "post": { "operationId": "stopOptionalProcessing", "summary": "Stop optional account processing", "tags": ["security-audit-privacy"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Reusing the correlation identifier for the same Privacy Request replays the result without repeating effects.", "x-authentication-note": "Requires recent authentication.", "security": [{"platformSession": []}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, {"name": "privacyRequestId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}} ], "responses": { "200": {"description": "Optional processing stopped and necessary processing explained", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/StopOptionalProcessingEnvelope"}, "example": {"data": { "optional_processing": "stopped", "necessary_processing": "continues_while_account_is_active", "necessary_purposes": ["account_operation", "security_and_fraud_prevention", "service_delivery", "required_retention", "legal_obligations"], "account_deletion_path": "/api/v1/platform-account" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/admin/operations/quotas.set": { "post": { "operationId": "setProjectQuota", "summary": "Set one Project Client quota", "tags": ["usage-quotas-administration"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "The latest valid values replace this resource quota. Repeating identical values leaves the effective quota unchanged.", "x-authentication-note": "Requires an active Platform Operator with quotas responsibility, matching environment and Project Client scope, plus recent passkey or recovery-code authentication.", "security": [{"platformSession": []}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["project_client_id", "parameters"], "properties": { "project_client_id": {"type": "string", "format": "uuid"}, "parameters": { "type": "object", "additionalProperties": false, "required": ["resource"], "properties": { "resource": {"type": "string", "enum": ["api_traffic", "storage_bytes", "deliveries", "events", "scheduled_invocations", "realtime_connections", "payment_transactions", "audit_retention"]}, "soft_limit": {"type": ["integer", "null"], "minimum": 1}, "hard_limit": {"type": ["integer", "null"], "minimum": 1}, "window_seconds": {"type": ["integer", "null"], "minimum": 60, "maximum": 2678400, "default": 3600} } } } }, "example": { "project_client_id": "30000000-0000-4000-8000-000000000003", "parameters": { "resource": "api_traffic", "soft_limit": 800, "hard_limit": 1000, "window_seconds": 3600 } } }}}, "responses": { "200": {"description": "Project Client quota updated", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["updated"], "properties": {"updated": {"type": "boolean", "enum": [true]}} }} }, "example": {"data": {"updated": true}} }}}, "401": {"$ref": "#/components/responses/PlatformSessionUnauthorized"}, "403": {"$ref": "#/components/responses/LegalAccessRequired"}, "422": {"$ref": "#/components/responses/AdministrativeOperationRejected"} } } }, "/admin/operations/browser-origins.register": { "post": { "operationId": "registerProjectClientBrowserOrigin", "summary": "Register an exact Project Client Browser Origin", "tags": ["realtime"], "x-documentation": false, "x-stability": "stable", "x-idempotency": "Equivalent normalized origins return the existing active registration.", "x-authentication-note": "Requires an active Platform Operator with clients responsibility, matching environment and Project Client scope, plus recent passkey or recovery-code authentication.", "security": [{"platformSession": []}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["project_client_id", "parameters"], "properties": {"project_client_id": {"type": "string", "format": "uuid"}, "parameters": {"type": "object", "required": ["origin"], "properties": {"origin": {"type": "string", "format": "uri"}}}}}}}}, "responses": {"200": {"description": "Normalized Browser Origin registration", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object", "required": ["id", "origin"], "properties": {"id": {"type": "string", "format": "uuid"}, "origin": {"type": "string", "format": "uri"}}}}}}}}, "401": {"$ref": "#/components/responses/PlatformSessionUnauthorized"}, "403": {"$ref": "#/components/responses/LegalAccessRequired"}, "422": {"$ref": "#/components/responses/AdministrativeOperationRejected"}} } }, "/admin/operations/browser-origins.list": { "post": { "operationId": "listProjectClientBrowserOrigins", "summary": "List active Project Client Browser Origins", "tags": ["realtime"], "x-documentation": false, "x-stability": "stable", "x-idempotency": "Safe scoped read; retries do not change Browser Origin state.", "x-authentication-note": "Requires an active Platform Operator with clients responsibility, matching environment and Project Client scope, plus recent passkey or recovery-code authentication.", "security": [{"platformSession": []}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["project_client_id", "parameters"], "properties": {"project_client_id": {"type": "string", "format": "uuid"}, "parameters": {"type": "object", "maxProperties": 0}}}}}}, "responses": {"200": {"description": "Active exact Browser Origins", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object", "required": ["origins"], "properties": {"origins": {"type": "array", "items": {"type": "object", "required": ["id", "origin"], "properties": {"id": {"type": "string", "format": "uuid"}, "origin": {"type": "string", "format": "uri"}}}}}}}}}}}, "401": {"$ref": "#/components/responses/PlatformSessionUnauthorized"}, "403": {"$ref": "#/components/responses/LegalAccessRequired"}, "422": {"$ref": "#/components/responses/AdministrativeOperationRejected"}} } }, "/admin/operations/browser-origins.revoke": { "post": { "operationId": "revokeProjectClientBrowserOrigin", "summary": "Revoke a Project Client Browser Origin", "tags": ["realtime"], "x-documentation": false, "x-stability": "stable", "x-idempotency": "A successful revocation removes browser access; repeating it returns a validation conflict.", "x-authentication-note": "Requires an active Platform Operator with clients responsibility, matching environment and Project Client scope, plus recent passkey or recovery-code authentication.", "security": [{"platformSession": []}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["project_client_id", "parameters"], "properties": {"project_client_id": {"type": "string", "format": "uuid"}, "parameters": {"type": "object", "required": ["browser_origin_id"], "properties": {"browser_origin_id": {"type": "string", "format": "uuid"}}}}}}}}, "responses": {"200": {"description": "Browser Origin revoked", "content": {"application/json": {"schema": {"type": "object", "required": ["data"], "properties": {"data": {"type": "object", "required": ["id", "revoked"], "properties": {"id": {"type": "string", "format": "uuid"}, "revoked": {"type": "boolean", "enum": [true]}}}}}}}}, "401": {"$ref": "#/components/responses/PlatformSessionUnauthorized"}, "403": {"$ref": "#/components/responses/LegalAccessRequired"}, "422": {"$ref": "#/components/responses/AdministrativeOperationRejected"}} } }, "/feature-configuration": { "get": { "operationId": "getFeatureConfiguration", "summary": "Get the latest Feature Flag and Configuration version", "tags": ["feature-flags-configuration"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read. Send If-None-Match with the last ETag to receive 304 when the version is unchanged.", "security": [{"projectCredential": ["configuration:read"]}], "parameters": [ {"$ref": "#/components/parameters/CorrelationId"}, { "name": "If-None-Match", "in": "header", "required": false, "schema": {"type": "string"}, "description": "ETag returned with the last valid configuration." } ], "responses": { "200": { "description": "Latest immutable client-scoped configuration version", "headers": { "ETag": {"schema": {"type": "string"}}, "Cache-Control": {"schema": {"type": "string"}, "description": "private, max-age=300"}, "Vary": {"schema": {"type": "string"}, "description": "Authorization"} }, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/FeatureConfigurationEnvelope"}, "example": {"data": { "id": "8a000000-0000-4000-8000-000000000001", "version": 7, "published_at": "2026-08-01T01:00:00Z", "max_age_seconds": 300, "flags": { "new_checkout": {"enabled": true, "safe_default": false} }, "configuration": {"support_url": "https://support.example.com"}, "secret_references": { "mailgun": "projects/minicenter/secrets/mailgun-api-key/versions/latest" } }} }} }, "304": {"description": "The cached version is still current"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"description": "No configuration version has been published for this Project Client", "content": {"application/json": { "schema": { "type": "object", "required": ["message"], "properties": {"message": {"type": "string"}} }, "example": {"message": "No records found."} }}} } } }, "/advertising/placements": { "post": { "operationId": "defineAdvertisingPlacement", "summary": "Define an immutable advertising Placement", "tags": ["advertising-sponsorship"], "x-documentation": true, "x-idempotency": "The body idempotency_key safely replays the same Placement version.", "x-stability": "stable", "security": [{"projectCredential": ["advertising:placements"]}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["code", "idempotency_key"], "properties": { "code": {"type": "string", "maxLength": 120}, "image_preset_ids": {"type": "array", "uniqueItems": true, "items": {"type": "string", "format": "uuid"}}, "native_fields": {"type": "array", "uniqueItems": true, "items": {"type": "string", "enum": ["title", "body", "call_to_action"]}}, "targeting_schema": {"type": "object"}, "idempotency_key": {"type": "string", "maxLength": 180} } }, "example": { "code": "article-sidebar", "image_preset_ids": ["8a000000-0000-4000-8000-000000000101"], "native_fields": ["title", "body", "call_to_action"], "targeting_schema": {"section": ["technology", "business"]}, "idempotency_key": "placement-article-sidebar-v1" } } } }, "responses": { "200": { "description": "Immutable Placement version", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": { "type": "object", "required": ["id", "code", "version"], "properties": { "id": {"type": "string", "format": "uuid"}, "code": {"type": "string"}, "version": {"type": "integer", "minimum": 1} } } } }, "example": {"data": {"id": "8a000000-0000-4000-8000-000000000102", "code": "article-sidebar", "version": 1}} } } }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"description": "The Placement contract is invalid"} } } }, "/advertising/house-ads": { "post": { "operationId": "configureAdvertisingHouseAd", "security": [{"projectCredential": ["advertising:placements"]}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["placement_version_id", "creative_version_id", "idempotency_key"], "properties": { "placement_version_id": {"type": "string", "format": "uuid"}, "creative_version_id": {"type": "string", "format": "uuid"}, "priority": {"type": "integer", "minimum": 0, "maximum": 1000}, "idempotency_key": {"type": "string", "maxLength": 180} } } } } }, "responses": { "200": { "description": "Immutable reviewed House Ad configuration", "content": {"application/json": {"schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id"], "properties": {"id": {"type": "string", "format": "uuid"}} }} }}} } } } }, "/advertising/ad-decisions": { "post": { "operationId": "createAdvertisingAdDecision", "summary": "Create an advertising Ad Decision", "tags": ["advertising-sponsorship"], "x-documentation": true, "x-idempotency": "Each request creates a short-lived signed decision; reuse the returned interaction URLs instead of replaying the request.", "x-stability": "stable", "security": [{"projectCredential": ["advertising:serve"]}], "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["placement_code", "frequency_token"], "properties": { "placement_code": {"type": "string", "maxLength": 120}, "image_preset_id": {"type": ["string", "null"], "format": "uuid"}, "targeting": {"type": "object", "additionalProperties": {"type": "string"}}, "frequency_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } }, "example": { "placement_code": "article-sidebar", "image_preset_id": "8a000000-0000-4000-8000-000000000101", "targeting": {"section": "technology"}, "frequency_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "responses": { "200": { "description": "Signed paid or House Ad Decision, or null for no-fill", "content": {"application/json": {"schema": { "type": "object", "required": ["data"], "properties": {"data": {"oneOf": [ {"$ref": "#/components/schemas/AdDecision"}, {"type": "null"} ]}} }, "example": {"data": null}}} }, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"description": "The Placement or Targeting Context is invalid"} } } }, "/advertising/viewable-impressions": { "post": { "operationId": "recordAdvertisingViewableImpression", "summary": "Record a verified Viewable Impression", "tags": ["advertising-sponsorship"], "x-documentation": true, "x-idempotency": "The signed decision token deduplicates repeated Viewable Impression submissions.", "x-stability": "stable", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["token", "visible_ratio_basis_points", "duration_milliseconds"], "properties": { "token": {"type": "string", "maxLength": 4096}, "visible_ratio_basis_points": {"type": "integer", "minimum": 0, "maximum": 10000}, "duration_milliseconds": {"type": "integer", "minimum": 0, "maximum": 3600000} } }, "example": { "token": "signed-ad-decision-token", "visible_ratio_basis_points": 5000, "duration_milliseconds": 1000 } } } }, "responses": { "200": { "description": "Deduplicated Viewable Impression and any atomic CPM charge", "content": {"application/json": {"schema": { "type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/AdInteraction"}} }, "example": {"data": {"recorded": true, "charged_minor": 0, "destination_url": null, "attribution_token": null}}}} }, "422": {"description": "The token is invalid, expired, or does not meet the viewability threshold"} } } }, "/advertising/clicks": { "get": { "operationId": "recordAdvertisingClick", "summary": "Record a Click and redirect to reviewed creative", "tags": ["advertising-sponsorship"], "x-documentation": true, "x-idempotency": "The signed decision token charges at most once; repeated requests redirect without another charge.", "x-stability": "stable", "security": [], "parameters": [{ "name": "token", "in": "query", "required": true, "schema": {"type": "string", "maxLength": 4096} }], "responses": { "302": { "description": "Redirect to the immutable reviewed Creative destination", "headers": { "Location": {"required": true, "schema": {"type": "string", "format": "uri"}}, "Cache-Control": {"required": true, "schema": {"type": "string", "example": "no-store"}}, "Referrer-Policy": {"required": true, "schema": {"type": "string", "example": "no-referrer"}} } }, "422": {"description": "The signed decision token is invalid or expired"} } } }, "/advertising/revenue-share-rules": { "post": { "operationId": "configureAdvertisingRevenueShareRule", "security": [{"projectCredential": ["advertising:reports"]}], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["publisher_basis_points", "effective_at", "idempotency_key"], "properties": { "placement_version_id": {"type": ["string", "null"], "format": "uuid"}, "publisher_basis_points": {"type": "integer", "minimum": 0, "maximum": 10000}, "effective_at": {"type": "string", "format": "date-time"}, "idempotency_key": {"type": "string", "maxLength": 180} } }}} }, "responses": {"200": {"description": "Immutable effective-dated revenue-share rule"}} } }, "/advertising/conversion-types": { "post": { "operationId": "registerAdvertisingConversionType", "security": [{"projectCredential": ["advertising:reports"]}], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["code", "attribution_window_days", "idempotency_key"], "properties": { "code": {"type": "string", "pattern": "^[a-z][a-z0-9_]{1,79}$"}, "attribution_window_days": {"type": "integer", "minimum": 1, "maximum": 90}, "idempotency_key": {"type": "string", "maxLength": 180} } }}} }, "responses": {"200": {"description": "Preregistered Conversion type"}} } }, "/advertising/conversions": { "post": { "operationId": "reportAdvertisingConversion", "security": [{"projectCredential": ["advertising:reports"]}], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["conversion_type", "conversion_id", "attribution_token"], "properties": { "conversion_type": {"type": "string"}, "conversion_id": {"type": "string", "format": "uuid"}, "attribution_token": {"type": "string", "maxLength": 4096}, "value_minor": {"type": ["integer", "null"], "minimum": 0} } }}} }, "responses": {"200": {"description": "Deduplicated server-to-server Conversion"}} } }, "/advertising/reports": { "get": { "operationId": "getAdvertisingAggregateReport", "security": [{"projectCredential": ["advertising:reports"]}], "parameters": [ {"name": "starts_at", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}}, {"name": "ends_at", "in": "query", "required": true, "schema": {"type": "string", "format": "date-time"}} ], "responses": {"200": {"description": "Aggregate Advertising report with freshness and financial reconciliation"}} } }, "/advertising/subject-linkage": { "delete": { "operationId": "forgetAdvertisingSubject", "security": [{"projectCredential": ["accounts:deletion"]}], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["subject"], "properties": {"subject": {"type": "string", "maxLength": 500}} }}} }, "responses": {"200": {"description": "Client-scoped Advertising subject linkage removed"}} } }, "/admin/advertising/legal-holds": { "post": { "operationId": "createAdvertisingLegalHold", "security": [{"platformSession": []}], "requestBody": { "required": true, "content": {"application/json": {"schema": { "type": "object", "additionalProperties": false, "required": ["project_client_id", "data_type", "period_starts_at", "period_ends_at", "expires_at", "reason"], "properties": { "project_client_id": {"type": "string", "format": "uuid"}, "data_type": {"type": "string", "enum": ["exposure", "interaction", "conversion", "decision"]}, "period_starts_at": {"type": "string", "format": "date-time"}, "period_ends_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "reason": {"type": "string", "maxLength": 500} } }}} }, "responses": {"200": {"description": "Audited scoped and expiring Advertising legal hold"}} } }, "/admin/advertising/archives/{batchId}": { "get": { "operationId": "replayAdvertisingArchive", "security": [{"platformSession": []}], "parameters": [ {"name": "batchId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 1000}} ], "responses": {"200": {"description": "Verified bounded Advertising archive replay"}} } }, "/payment-transactions": { "post": { "operationId": "createPaymentTransaction", "summary": "Create a Payment Transaction", "tags": ["payments"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Retry an uncertain request with the same key and unchanged body.", "security": [{"projectCredential": ["payments:write"]}], "parameters": [ {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["project_order_reference", "amount", "item_name", "trade_description"], "properties": { "project_order_reference": {"type": "string", "maxLength": 180}, "amount": {"type": "integer", "minimum": 1, "maximum": 99999999}, "item_name": {"type": "string", "maxLength": 200}, "trade_description": {"type": "string", "maxLength": 200}, "recurring": { "type": "object", "additionalProperties": false, "required": ["period_type", "frequency", "execution_count"], "properties": { "period_type": {"type": "string", "enum": ["D", "M", "Y"]}, "frequency": {"type": "integer", "minimum": 1}, "execution_count": {"type": "integer", "minimum": 1} } } } }, "example": { "project_order_reference": "sandbox-order-1001", "amount": 100, "item_name": "Sandbox item", "trade_description": "MiniCenter sandbox payment" } }}}, "responses": { "200": {"description": "Payment Transaction and signed provider checkout fields", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status", "checkout_url", "checkout_fields"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending"]}, "checkout_url": {"type": "string", "format": "uri"}, "checkout_fields": {"type": "object"} } }} }, "example": {"data": { "id": "70000000-0000-4000-8000-000000000007", "status": "pending", "checkout_url": "https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5", "checkout_fields": {"MerchantTradeNo": "MC2026073000000001", "TotalAmount": 100} }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/payment-transactions/{paymentTransactionId}": { "get": { "operationId": "getPaymentTransaction", "summary": "Get a Payment Transaction", "tags": ["payments"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Safe read; retries do not change the Payment Transaction.", "security": [{"projectCredential": ["payments:read"]}], "parameters": [ {"name": "paymentTransactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/CorrelationId"} ], "responses": { "200": {"description": "Project Client scoped Payment Transaction", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "project_order_reference", "amount", "currency", "status"], "properties": { "id": {"type": "string", "format": "uuid"}, "project_order_reference": {"type": "string", "maxLength": 180}, "amount": {"type": "integer", "minimum": 1}, "currency": {"type": "string", "const": "TWD"}, "status": {"type": "string", "enum": ["pending", "settled", "failed"]}, "recurring": { "type": ["object", "null"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string"} } } } }} }, "example": {"data": { "id": "70000000-0000-4000-8000-000000000007", "project_order_reference": "sandbox-order-1001", "amount": 100, "currency": "TWD", "status": "settled" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/payment-transactions/{paymentTransactionId}/cancel-recurring": { "post": { "operationId": "cancelRecurringPayment", "summary": "Cancel recurring charges", "tags": ["payments"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Reusing the same key returns the existing cancellation outcome.", "security": [{"projectCredential": ["payments:write"]}], "parameters": [ {"name": "paymentTransactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "responses": { "200": {"description": "Recurring cancellation outcome", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["processing", "succeeded", "failed"]} } }} }, "example": {"data": { "id": "71000000-0000-4000-8000-000000000007", "status": "succeeded" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/payment-transactions/{paymentTransactionId}/refunds": { "post": { "operationId": "createRefund", "summary": "Create a Refund", "tags": ["payments"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Retry the same business Refund with the same key and amount.", "security": [{"projectCredential": ["payments:write"]}], "parameters": [ {"name": "paymentTransactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["amount"], "properties": {"amount": {"type": "integer", "minimum": 1}} }, "example": {"amount": 100} }}}, "responses": { "200": {"description": "Refund outcome", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["processing", "succeeded", "failed"]} } }} }, "example": {"data": { "id": "72000000-0000-4000-8000-000000000007", "status": "succeeded" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/payment-transactions/{paymentTransactionId}/invoice-issuances": { "post": { "operationId": "issueInvoice", "summary": "Issue an electronic Invoice", "tags": ["payments"], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Requires Idempotency-Key. Retry the same Invoice Issuance with the same key and items.", "security": [{"projectCredential": ["payments:write"]}], "parameters": [ {"name": "paymentTransactionId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"$ref": "#/components/parameters/WriteIdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": {"required": true, "content": {"application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["customer_email", "items"], "properties": { "customer_email": {"type": "string", "format": "email", "maxLength": 80}, "customer_identifier": {"type": ["string", "null"], "minLength": 8, "maxLength": 8}, "customer_name": {"type": ["string", "null"], "maxLength": 60}, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": ["name", "count", "unit", "price", "amount"], "properties": { "name": {"type": "string", "maxLength": 100}, "count": {"type": "integer", "minimum": 1}, "unit": {"type": "string", "maxLength": 6}, "price": {"type": "integer", "minimum": 1}, "amount": {"type": "integer", "minimum": 1} } } } } }, "example": { "customer_email": "sandbox-buyer@example.test", "items": [{"name": "Sandbox item", "count": 1, "unit": "item", "price": 100, "amount": 100}] } }}}, "responses": { "200": {"description": "Invoice Issuance outcome", "content": {"application/json": { "schema": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["processing", "succeeded", "failed"]} } }} }, "example": {"data": { "id": "73000000-0000-4000-8000-000000000007", "status": "succeeded" }} }}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"} } } }, "/platform-sessions": { "post": { "operationId": "createPlatformSession", "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["email", "password"], "properties": { "email": {"type": "string", "format": "email"}, "password": {"type": "string", "minLength": 1, "maxLength": 128}, "turnstile_token": {"type": "string", "maxLength": 2048} } } } } }, "responses": { "204": { "description": "Platform Session created in a Secure HttpOnly cookie" }, "422": { "description": "Generic authentication failure", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "429": { "description": "Layered authentication throttle reached", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } } } } }, "/platform-account": { "get": { "operationId": "platformAccount", "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "responses": { "200": { "description": "Authenticated Platform Account", "content": { "application/json": { "schema": { "type": "object", "required": ["data"], "properties": { "data": {"$ref": "#/components/schemas/PlatformAccount"} } } } } }, "401": { "description": "Invalid or expired Platform Session", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } } } } }, "/platform-session": { "delete": { "operationId": "deletePlatformSession", "parameters": [{"$ref": "#/components/parameters/CorrelationId"}], "responses": { "204": {"description": "Platform Session revoked"}, "401": { "description": "Invalid or expired Platform Session", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } } } } }, "/noop": { "post": { "operationId": "noop", "summary": "Validate the MiniCenter request contract", "tags": ["developer-tooling"], "security": [], "x-documentation": true, "x-stability": "stable", "x-idempotency": "Idempotency-Key is required. Reusing the same key with the same payload replays the original result; using it with another payload returns 409.", "parameters": [ {"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/CorrelationId"} ], "requestBody": { "required": true, "content": { "application/json": { "example": { "money": {"currency": "TWD", "minor": 100} }, "schema": { "type": "object", "required": ["money"], "properties": { "money": {"$ref": "#/components/schemas/Money"} } } } } }, "responses": { "202": { "description": "Contract accepted without a side effect", "content": { "application/json": { "example": { "data": { "money": {"currency": "TWD", "minor": 100}, "status": "queued" }, "meta": { "release": "0.1.0", "idempotency_key": "contract-example", "correlation_id": "123e4567-e89b-12d3-a456-426614174000", "replayed": false } }, "schema": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "object", "required": ["money", "status"], "properties": { "money": {"$ref": "#/components/schemas/Money"}, "status": {"type": "string", "enum": ["queued", "completed"]} } }, "meta": { "type": "object", "required": ["release", "idempotency_key", "correlation_id", "replayed"], "properties": { "release": {"type": "string"}, "idempotency_key": {"type": "string"}, "correlation_id": {"type": "string", "format": "uuid"}, "replayed": {"type": "boolean"} } } } } } } }, "422": { "description": "Invalid public request", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } }, "409": { "description": "Idempotency key reused for another payload", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } } } } }, "/noop/{idempotencyKey}": { "get": { "operationId": "noopStatus", "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "schema": {"type": "string", "maxLength": 255} }, {"$ref": "#/components/parameters/CorrelationId"} ], "responses": { "200": { "description": "No-op worker status", "content": { "application/json": { "schema": { "type": "object", "required": ["data", "meta"], "properties": { "data": { "type": "object", "required": ["status"], "properties": { "status": {"type": "string", "enum": ["queued", "completed"]} } }, "meta": { "type": "object", "required": ["idempotency_key", "correlation_id"], "properties": { "idempotency_key": {"type": "string"}, "correlation_id": {"type": "string", "format": "uuid"} } } } } } } }, "404": { "description": "No-op operation not found", "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"} } } } } } } }, "components": { "securitySchemes": { "projectCredential": { "type": "http", "scheme": "bearer" }, "platformSession": { "type": "apiKey", "in": "cookie", "name": "minicenter_session" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "maxLength": 255} }, "WriteIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "maxLength": 120} }, "CorrelationId": { "name": "X-Correlation-ID", "in": "header", "required": false, "schema": {"type": "string", "format": "uuid"} } }, "responses": { "Unauthorized": { "description": "Invalid or revoked Project Credential", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "Forbidden": { "description": "Project Credential lacks the required scope", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "ValidationError": { "description": "Request violates the public contract", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}} }, "QuotaExceeded": { "description": "Project Client hard quota reached", "headers": { "Retry-After": { "description": "Seconds until the current quota window ends", "schema": {"type": "integer", "minimum": 1} } }, "content": {"application/json": { "schema": {"$ref": "#/components/schemas/QuotaExceededEnvelope"}, "example": {"error": { "code": "platform_quota_exceeded", "message": "The platform resource hard limit has been reached.", "retryable": true, "details": { "resource": "api_traffic", "used": 1000, "limit": 1000, "retry_after_seconds": 312 }, "correlation_id": "20000000-0000-4000-8000-000000000016" }} }} }, "PlatformSessionUnauthorized": { "description": "An active Platform Session is required", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": { "code": "unauthenticated", "message": "Authentication is required.", "retryable": false, "correlation_id": "20000000-0000-4000-8000-000000000016", "details": {} }} }} }, "LegalAccessRequired": { "description": "Current Terms and Privacy Notice acceptance is required", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": { "code": "legal_acceptance_required", "message": "Review and accept the current Terms and Privacy Notice to continue.", "retryable": false, "correlation_id": "20000000-0000-4000-8000-000000000016", "details": {} }} }} }, "AdministrativeOperationRejected": { "description": "Operator authorization, Project Client scope, environment, recent strong authentication, or request validation failed", "content": {"application/json": { "schema": {"$ref": "#/components/schemas/ValidationErrorEnvelope"}, "example": { "message": "The Platform Operator is not authorized for this responsibility and Project Client.", "errors": { "operator": ["The Platform Operator is not authorized for this responsibility and Project Client."] } } }} } }, "schemas": { "FileUploadGrantEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["file_object_id", "upload_token", "expires_at"], "properties": { "file_object_id": {"type": "string", "format": "uuid"}, "upload_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "expires_at": {"type": "string", "format": "date-time"} } }} }, "FileUploadEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["file_object_id"], "properties": {"file_object_id": {"type": "string", "format": "uuid"}} }} }, "FileObjectEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status", "rejection_reason"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["quarantine", "scanning", "available", "rejected"]}, "rejection_reason": {"type": ["string", "null"]} } }} }, "DomainEventEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id"], "properties": {"id": {"type": "string", "format": "uuid"}} }} }, "NotificationIntentEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["intent_id", "delivery_id", "status"], "properties": { "intent_id": {"type": "string", "format": "uuid"}, "delivery_id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending"]} } }} }, "NotificationDeliveryEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "channel", "status", "attempts", "provider_status", "last_error_code"], "properties": { "id": {"type": "string", "format": "uuid"}, "channel": {"type": "string", "enum": ["email", "fcm", "apns", "line", "web_push"]}, "status": {"type": "string", "enum": ["pending", "retry", "sent", "rejected", "suppressed", "unknown", "failed", "accepted", "unavailable", "delivered", "bounced", "complained"]}, "attempts": {"type": "integer", "minimum": 0}, "provider_status": {"type": ["string", "null"]}, "last_error_code": {"type": ["string", "null"]} } }} }, "RegisteredScheduledOperationEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id"], "properties": {"id": {"type": "string", "format": "uuid"}} }} }, "InvocationScheduleCreatedEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["schedule_id", "invocation_id"], "properties": { "schedule_id": {"type": "string", "format": "uuid"}, "invocation_id": {"type": "string", "format": "uuid"} } }} }, "InvocationScheduleEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "status", "recurring", "quota", "invocations"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["active", "quota_paused", "cancelled"]}, "recurring": {"type": "boolean"}, "quota": { "oneOf": [ {"type": "null"}, { "type": "object", "required": ["resource", "used", "limit", "retry_at"], "properties": { "resource": {"type": "string"}, "used": {"type": "integer", "minimum": 0}, "limit": {"type": "integer", "minimum": 0}, "retry_at": {"type": "string"} } } ] }, "invocations": { "type": "array", "items": {"$ref": "#/components/schemas/ScheduledInvocation"} } } }} }, "ScheduledInvocationEnvelope": { "type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/ScheduledInvocation"}} }, "ScheduledInvocation": { "type": "object", "required": ["id", "status", "attempts", "last_error_code"], "properties": { "id": {"type": "string", "format": "uuid"}, "scheduled_for": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "processing", "retry", "succeeded", "dead_letter", "cancelled"]}, "attempts": {"type": "integer", "minimum": 0}, "last_error_code": {"type": ["string", "null"]} } }, "PrivacyRequestEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": [ "id", "platform_account_id", "type", "status", "acknowledgement_due_at", "response_due_at", "progress_summary", "progress_at", "extended_response_due_at", "closed_unverified_at", "fallback_contact", "legal_holds", "required_retention" ], "properties": { "id": {"type": "string", "format": "uuid"}, "platform_account_id": {"type": "string", "format": "uuid"}, "type": {"type": "string", "enum": ["access", "export", "correction", "deletion", "stop_processing"]}, "status": {"type": "string", "enum": ["pending_verification", "verified", "in_progress", "completed", "closed_unverified"]}, "acknowledgement_due_at": {"type": "string", "format": "date-time"}, "response_due_at": {"type": ["string", "null"], "format": "date-time"}, "progress_summary": {"type": ["string", "null"]}, "progress_at": {"type": ["string", "null"], "format": "date-time"}, "extended_response_due_at": {"type": ["string", "null"], "format": "date-time"}, "closed_unverified_at": {"type": ["string", "null"], "format": "date-time"}, "fallback_contact": {"type": "string", "format": "email"}, "legal_holds": {"type": "array", "items": { "type": "object", "required": ["purpose", "reason", "expires_at"], "properties": { "purpose": {"type": "string"}, "reason": {"type": "string"}, "expires_at": {"type": "string", "format": "date-time"} } }}, "required_retention": {"type": "array", "items": { "type": "object", "required": ["project_client_id", "reason", "until"], "properties": { "project_client_id": {"type": "string", "format": "uuid"}, "reason": {"type": "string"}, "until": {"type": "string", "format": "date-time"} } }}, "account_deletion": { "type": "object", "required": ["id", "status", "deadline_at"], "properties": { "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["pending", "completed"]}, "deadline_at": {"type": "string", "format": "date-time"} } } } }} }, "PrivacyExportEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "download_path", "expires_at"], "properties": { "id": {"type": "string", "format": "uuid"}, "download_path": {"type": "string"}, "expires_at": {"type": "string", "format": "date-time"} } }} }, "PrivacyCorrectionEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["outcome", "evidence"], "properties": { "outcome": {"type": "string", "enum": ["corrected", "append_only_correction"]}, "evidence": { "type": "object", "required": ["type", "reference"], "properties": { "type": {"type": "string", "enum": ["direct_change", "append_only_correction"]}, "reference": {"type": "string"} } } } }} }, "StopOptionalProcessingEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["optional_processing", "necessary_processing", "necessary_purposes", "account_deletion_path"], "properties": { "optional_processing": {"type": "string", "enum": ["stopped"]}, "necessary_processing": {"type": "string", "enum": ["continues_while_account_is_active"]}, "necessary_purposes": {"type": "array", "items": {"type": "string"}}, "account_deletion_path": {"type": "string"} } }} }, "FeatureConfigurationEnvelope": { "type": "object", "required": ["data"], "properties": {"data": { "type": "object", "required": ["id", "version", "published_at", "max_age_seconds", "flags", "configuration", "secret_references"], "properties": { "id": {"type": "string", "format": "uuid"}, "version": {"type": "integer", "minimum": 1}, "published_at": {"type": "string"}, "max_age_seconds": {"type": "integer", "minimum": 0, "maximum": 86400}, "flags": { "type": "object", "maxProperties": 100, "additionalProperties": { "type": "object", "required": ["enabled", "safe_default"], "properties": { "enabled": {"type": "boolean"}, "safe_default": {"type": "boolean"} } } }, "configuration": {"type": "object", "maxProperties": 100}, "secret_references": { "type": "object", "maxProperties": 100, "additionalProperties": {"type": "string"} } } }} }, "ProjectAuditFact": { "type": "object", "additionalProperties": false, "required": ["actor_id", "action", "resource_type", "resource_id", "outcome"], "properties": { "actor_id": {"type": "string", "maxLength": 180, "pattern": "^(?:[A-Za-z][A-Za-z0-9_]*:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}, "action": {"type": "string", "maxLength": 180, "pattern": "^[a-z][a-z0-9_.-]+$"}, "resource_type": {"type": "string", "maxLength": 120, "pattern": "^[A-Z][A-Za-z0-9]+$"}, "resource_id": {"type": "string", "maxLength": 180, "pattern": "^(?:[A-Za-z][A-Za-z0-9_]*:)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}, "outcome": {"type": "string", "enum": ["succeeded", "failed", "denied"]} } }, "ProjectAuditEnvelope": { "type": "object", "additionalProperties": false, "required": ["data"], "properties": {"data": { "type": "object", "additionalProperties": false, "required": ["id"], "properties": {"id": {"type": "string", "format": "uuid"}} }} }, "ProjectClient": { "type": "object", "additionalProperties": false, "required": ["id", "name", "environment", "scopes"], "properties": { "id": {"type": "string", "format": "uuid"}, "name": {"type": "string"}, "environment": { "type": "string", "enum": ["development", "sandbox", "staging", "production"] }, "scopes": { "type": "array", "items": {"type": "string"} } } }, "IdentityMigrationTransactionEnvelope": { "type": "object", "additionalProperties": false, "required": ["data"], "properties": {"data": { "type": "object", "additionalProperties": false, "required": ["id", "project_client_id", "legacy_subject", "email", "locale", "correlation_id", "expires_at", "status", "account_id"], "properties": { "id": {"type": "string", "format": "uuid"}, "project_client_id": {"type": "string", "format": "uuid"}, "legacy_subject": {"type": "string", "maxLength": 255}, "email": {"type": "string", "format": "email"}, "locale": {"type": "string", "maxLength": 20}, "correlation_id": {"type": "string", "format": "uuid"}, "expires_at": {"type": "string", "format": "date-time"}, "status": {"type": "string", "enum": ["pending", "expired", "link_pending", "completed"]}, "account_id": {"type": ["string", "null"], "format": "uuid"} } }} }, "CreatedIdentityMigrationTransactionEnvelope": { "type": "object", "additionalProperties": false, "required": ["data"], "properties": {"data": { "type": "object", "additionalProperties": false, "required": ["id", "project_client_id", "legacy_subject", "email", "locale", "correlation_id", "expires_at", "status", "account_id", "flow_token"], "properties": { "id": {"type": "string", "format": "uuid"}, "project_client_id": {"type": "string", "format": "uuid"}, "legacy_subject": {"type": "string", "maxLength": 255}, "email": {"type": "string", "format": "email"}, "locale": {"type": "string", "maxLength": 20}, "correlation_id": {"type": "string", "format": "uuid"}, "expires_at": {"type": "string", "format": "date-time"}, "status": {"type": "string", "enum": ["pending", "expired", "link_pending", "completed"]}, "account_id": {"type": ["string", "null"], "format": "uuid"}, "flow_token": {"type": "string", "pattern": "^[a-f0-9]{64}$"} } }} }, "PlatformAccount": { "type": "object", "additionalProperties": false, "required": ["id", "login_identifier"], "properties": { "id": {"type": "string", "format": "uuid"}, "login_identifier": {"type": "string", "format": "email"} } }, "Money": { "type": "object", "additionalProperties": false, "required": ["currency", "minor"], "properties": { "currency": {"type": "string", "pattern": "^[A-Z]{3}$"}, "minor": {"type": "integer"} } }, "Health": { "type": "object", "required": ["status", "release", "contracts"], "properties": { "status": {"const": "ok"}, "release": {"type": "string"}, "contracts": { "type": "object", "required": ["openapi", "events"], "properties": { "openapi": {"type": "string"}, "events": {"type": "string"} } } } }, "AdDecision": { "type": "object", "additionalProperties": false, "required": ["id", "inventory_type", "selection_version", "expires_at", "creative", "tracking"], "properties": { "id": {"type": "string", "format": "uuid"}, "inventory_type": {"type": "string", "enum": ["paid", "house"]}, "selection_version": {"type": "string"}, "expires_at": {"type": "string", "format": "date-time"}, "creative": { "type": "object", "required": ["format", "image_preset_id", "asset_url", "content"], "properties": { "format": {"type": "string", "enum": ["image", "native"]}, "image_preset_id": {"type": ["string", "null"], "format": "uuid"}, "asset_url": {"type": ["string", "null"]}, "content": {"type": "object", "additionalProperties": {"type": "string"}} } }, "tracking": { "type": "object", "required": ["token", "impression_url", "click_url"], "properties": { "token": {"type": "string"}, "impression_url": {"type": "string", "format": "uri"}, "click_url": {"type": "string", "format": "uri"} } } } }, "AdInteraction": { "type": "object", "additionalProperties": false, "required": ["recorded", "charged_minor", "destination_url"], "properties": { "recorded": {"type": "boolean"}, "charged_minor": {"type": "integer", "minimum": 0}, "destination_url": {"type": ["string", "null"], "format": "uri"}, "attribution_token": {"type": ["string", "null"]} } }, "ErrorEnvelope": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "retryable", "correlation_id", "details"], "properties": { "code": {"type": "string"}, "message": {"type": "string"}, "retryable": {"type": "boolean"}, "correlation_id": {"type": "string", "format": "uuid"}, "details": {"type": "object"} } } } }, "QuotaExceededEnvelope": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "retryable", "details", "correlation_id"], "properties": { "code": {"type": "string", "enum": ["platform_quota_exceeded"]}, "message": {"type": "string"}, "retryable": {"type": "boolean", "enum": [true]}, "details": { "type": "object", "required": ["resource", "used", "limit", "retry_after_seconds"], "properties": { "resource": {"type": "string", "enum": ["api_traffic", "storage_bytes", "deliveries", "events", "scheduled_invocations", "realtime_connections", "payment_transactions", "audit_retention"]}, "used": {"type": "integer", "minimum": 0}, "limit": {"type": "integer", "minimum": 1}, "retry_after_seconds": {"type": "integer", "minimum": 1} } }, "correlation_id": {"type": "string", "format": "uuid"} } } } }, "ValidationErrorEnvelope": { "type": "object", "required": ["message", "errors"], "properties": { "message": {"type": "string"}, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": {"type": "string"} } } } } } } }