{ "openapi": "3.1.0", "info": { "title": "Likerts development API", "version": "0.1.0", "description": "API contract with PostgreSQL persistence, tenant RLS and optional explicit development-only memory mode. Management accepts scoped service credentials or provider-neutral OIDC JWTs and keeps workspace membership and grants authoritative in Likerts. JSON request bodies have a 65536-byte limit. All content bounds count Unicode scalar values; objects reject unknown properties unless documented otherwise." }, "servers": [ { "url": "http://127.0.0.1:8080", "description": "Loopback-only development service" } ], "paths": { "/v1/surveys": { "post": { "operationId": "surveys_create", "summary": "Create a survey draft idempotently; identical retries return the original draft.", "security": [ { "managementBearer": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" }, "example": { "id": "10000000-0000-4000-8000-000000000001", "revision": 1, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "409": { "description": "The idempotency key was already used with a different payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "The idempotency key was already used with a different payload." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyCreateInput" }, "example": { "idempotencyKey": "survey-create-001", "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } } } }, "x-max-request-bytes": 65536, "x-required-scope": "surveys:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] }, "get": { "operationId": "surveys_list", "summary": "List workspace surveys.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" } }, "example": [ { "id": "10000000-0000-4000-8000-000000000001", "revision": 1, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } ] } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "surveys:read", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/surveys/{id}": { "put": { "operationId": "surveys_update", "summary": "Update a draft using its current revision.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" }, "example": { "id": "10000000-0000-4000-8000-000000000001", "revision": 2, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Resource absent or belongs to another workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource absent or belongs to another workspace." } } } } }, "409": { "description": "Stale revision, changed payload for an existing idempotency key, or a closed collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stale revision, changed payload for an existing idempotency key, or a closed collection." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID returned by creation.", "example": "10000000-0000-4000-8000-000000000001" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInput" }, "example": { "revision": 1, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } } } }, "x-max-request-bytes": 65536, "x-required-scope": "surveys:write" } }, "/v1/surveys/{id}/publish": { "post": { "operationId": "surveys_publish", "summary": "Publish an immutable version only when every customer-declared SDK installation supports its schema version.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" }, "example": { "surveyId": "10000000-0000-4000-8000-000000000001", "version": 1, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ], "sdkCapabilities": { "installations": [ { "target": "web", "sdkVersion": "0.0.1", "schemaVersions": [ 1, 2 ] } ] } } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Resource absent or belongs to another workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource absent or belongs to another workspace." } } } } }, "409": { "description": "Stale revision, changed payload for an existing idempotency key, or a closed collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stale revision, changed payload for an existing idempotency key, or a closed collection." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID returned by creation.", "example": "10000000-0000-4000-8000-000000000001" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishInput" }, "example": { "revision": 1, "sdkCapabilities": { "installations": [ { "target": "web", "sdkVersion": "0.0.1", "schemaVersions": [ 1, 2 ] } ] } } } } }, "x-max-request-bytes": 65536, "x-required-scope": "surveys:write" } }, "/v1/collections": { "post": { "operationId": "collections_create", "summary": "Create an immutable embedded collection only when every declared SDK installation supports the bound schema version. Identical retries return the original submission credential; handle it as a secret.", "security": [ { "managementBearer": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "example": { "id": "10000000-0000-4000-8000-000000000002", "surveyId": "10000000-0000-4000-8000-000000000001", "version": 1, "placement": "checkout", "token": "10000000-0000-4000-8000-000000000008", "accepting": true, "expiresAt": null, "responseCap": 100, "revoked": false, "sdkCapabilities": { "installations": [ { "target": "web", "sdkVersion": "0.0.1", "schemaVersions": [ 1, 2 ] } ] } } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Resource absent or belongs to another workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource absent or belongs to another workspace." } } } } }, "409": { "description": "The workspace already has 100 active collections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "The workspace already has 100 active collections." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionInput" }, "example": { "idempotencyKey": "collection-create-001", "surveyId": "10000000-0000-4000-8000-000000000001", "version": 1, "placement": "checkout", "responseCap": 100, "sdkCapabilities": { "installations": [ { "target": "web", "sdkVersion": "0.0.1", "schemaVersions": [ 1, 2 ] } ] } } } } }, "x-max-request-bytes": 65536, "x-required-scope": "collections:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/collections/{id}": { "patch": { "operationId": "collections_update", "summary": "Open or close collection acceptance, or irreversibly revoke its credential.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acceptance" }, "example": { "id": "10000000-0000-4000-8000-000000000002", "accepting": false, "revoked": false } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Resource absent or belongs to another workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource absent or belongs to another workspace." } } } } }, "409": { "description": "Reopening would exceed the workspace's active collection limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Reopening would exceed the workspace's active collection limit." } } } } }, "410": { "description": "The collection is expired or irrevocably revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "The collection is expired or irrevocably revoked." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID returned by creation.", "example": "10000000-0000-4000-8000-000000000002" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptanceInput" }, "example": { "accepting": false } } } }, "x-max-request-bytes": 65536, "x-required-scope": "collections:write" }, "get": { "operationId": "collections_get", "summary": "Fetch the immutable respondent configuration using a collection credential.", "security": [ { "collectionBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" }, "example": { "id": "10000000-0000-4000-8000-000000000002", "surveyId": "10000000-0000-4000-8000-000000000001", "version": 1, "placement": "checkout", "schema": { "schemaVersion": 1, "title": "Checkout feedback", "questions": [ { "id": "rating", "type": "scale", "label": "How was your experience?", "required": true, "min": 1, "max": 5 } ] } } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "Browser Origin is not in the exact collection allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Browser Origin is not in the exact collection allowlist." } } } } }, "410": { "description": "The collection credential was irrevocably revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "The collection credential was irrevocably revoked." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID returned by creation.", "example": "10000000-0000-4000-8000-000000000002" } ], "x-required-scope": null }, "options": { "operationId": "collection_config_preflight", "summary": "Validate exact browser Origin before collection transport.", "security": [], "x-interface-exempt": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Permitted origin; CORS response headers, no body." }, "400": { "description": "Invalid preflight request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid preflight request." } } } } }, "403": { "description": "Origin is not permitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Origin is not permitted." } } } } }, "404": { "description": "Collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Collection not found." } } } } }, "410": { "description": "Collection unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "Collection unavailable." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal error." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } } } }, "/v1/collections/{id}/security": { "put": { "operationId": "collections_security_update", "summary": "Configure exact browser origins and a per-collection request rate. Origins are browser policy, not authentication.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000002" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionSecurityInput" }, "example": { "allowedOrigins": [ "https://app.example.com" ], "requestsPerMinute": 6000 } } } }, "responses": { "200": { "description": "Applied policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionSecurity" }, "example": { "collectionId": "10000000-0000-4000-8000-000000000002", "allowedOrigins": [ "https://app.example.com" ], "requestsPerMinute": 6000 } } } }, "400": { "description": "Invalid origin or limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid origin or limit." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Collection not found." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "collections:write" } }, "/v1/collections/{id}/responses": { "post": { "operationId": "responses_submit", "summary": "Submit an unmetered response.", "security": [ { "collectionBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "responseId": "10000000-0000-4000-8000-000000000003", "collectionId": "10000000-0000-4000-8000-000000000002", "accepted": true } } } }, "400": { "description": "Invalid JSON, unknown fields or domain validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid JSON, unknown fields or domain validation failure." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "Browser Origin is not in the exact collection allowlist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Browser Origin is not in the exact collection allowlist." } } } } }, "409": { "description": "Changed payload for an existing idempotency key, a closed collection, or an exhausted response cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Changed payload for an existing idempotency key, a closed collection, or an exhausted response cap." } } } } }, "410": { "description": "The collection is expired or irrevocably revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "The collection is expired or irrevocably revoked." } } } } }, "413": { "description": "Request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Collection rate window exhausted; no new response is accepted." } } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource ID returned by creation.", "example": "10000000-0000-4000-8000-000000000002" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Submission" }, "example": { "idempotencyKey": "completed-response-001", "answers": { "rating": 5 }, "metadata": { "channel": "app" } } } } }, "x-max-request-bytes": 65536, "description": "Accepted responses are idempotent, counted for observability and never metered or charged.", "x-required-scope": null }, "options": { "operationId": "collection_submit_preflight", "summary": "Validate exact browser Origin before collection transport.", "security": [], "x-interface-exempt": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Permitted origin; CORS response headers, no body." }, "400": { "description": "Invalid preflight request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid preflight request." } } } } }, "403": { "description": "Origin is not permitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Origin is not permitted." } } } } }, "404": { "description": "Collection not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Collection not found." } } } } }, "410": { "description": "Collection unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "Collection unavailable." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal error." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } } } }, "/v1/responses": { "get": { "operationId": "responses_list", "summary": "Retrieve one stable snapshot page of workspace responses, optionally filtered by collection and acceptance time. Continue with nextCursor.", "description": "Responses are ordered by an immutable acceptance sequence. The first page fixes a snapshot boundary; responses accepted after that boundary are excluded from every continuation. nextCursor binds the original limit and filters. Supplying a different filter or limit with a cursor returns 400. acceptedFrom is inclusive and acceptedTo is exclusive.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponsePage" }, "example": { "items": [ { "receipt": { "responseId": "10000000-0000-4000-8000-000000000003", "collectionId": "10000000-0000-4000-8000-000000000002", "accepted": true }, "answers": { "rating": 5 }, "metadata": { "channel": "app" }, "acceptedAt": "2026-09-08T12:00:00Z" } ], "nextCursor": null } } } }, "400": { "description": "Invalid limit, time range or cursor; or cursor/query mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid limit, time range or cursor; or cursor/query mismatch." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "example": 100 }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque nextCursor returned by the preceding page." }, { "name": "collectionId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000002" }, { "name": "acceptedFrom", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive acceptance-time lower bound." }, { "name": "acceptedTo", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive acceptance-time upper bound." }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "x-required-scope": "responses:read" } }, "/v1/responses/{id}": { "delete": { "operationId": "responses_delete", "summary": "Erase one response's raw answers and metadata while preserving its minimal retry receipt and usage entry.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000003" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "204": { "description": "Raw answers and metadata erased; minimal retry/accounting record retained." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "No response in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No response in this workspace." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "responses:write" } }, "/v1/exports": { "post": { "operationId": "exports_create", "summary": "Create or idempotently retry a bounded asynchronous CSV or JSON response export.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportInput" }, "example": { "idempotencyKey": "export-001", "format": "json", "collectionId": "10000000-0000-4000-8000-000000000002" } } } }, "responses": { "202": { "description": "Queued, running, or already completed idempotent export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJob" }, "example": { "id": "10000000-0000-4000-8000-000000000004", "format": "json", "status": "queued", "createdAt": "2026-09-08T12:00:00Z", "expiresAt": "2026-09-09T12:00:00Z", "responseCount": null, "contentSha256": null, "manifest": null, "errorCode": null } } } }, "400": { "description": "Invalid format or filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid format or filters." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "409": { "description": "Idempotency key reused with changed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Idempotency key reused with changed input." } } } } }, "410": { "description": "The idempotent export job has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "The idempotent export job has expired." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "description": "The first request records a response snapshot boundary and returns immediately. Identical retries reuse the job; a failed job is requeued. Output is bounded to 64 MiB and expires after 24 hours.", "x-required-scope": "exports:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/exports/{id}": { "get": { "operationId": "exports_get", "summary": "Read an export job's status and stable schema manifest.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000004" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportJob" }, "example": { "id": "10000000-0000-4000-8000-000000000004", "format": "json", "status": "queued", "createdAt": "2026-09-08T12:00:00Z", "expiresAt": "2026-09-09T12:00:00Z", "responseCount": null, "contentSha256": null, "manifest": null, "errorCode": null } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "No export in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No export in this workspace." } } } } }, "410": { "description": "Export expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "Export expired or was revoked." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "exports:read", "description": "Authorized polling resumes queued work and reclaims expired execution leases within the caller workspace." }, "delete": { "operationId": "exports_revoke", "summary": "Irreversibly revoke export access and remove its stored object.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000004" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "204": { "description": "Revoked" }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "No export in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No export in this workspace." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "exports:write" } }, "/v1/exports/{id}/download": { "get": { "operationId": "exports_download", "summary": "Download a ready export as authenticated base64 content before its 24-hour expiry.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000004" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Ready export encoded for API, MCP and CLI transport.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDownload" }, "example": { "contentType": "application/json", "fileName": "responses.json", "contentBase64": "W10=", "contentSha256": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945", "manifest": { "formatVersion": 1, "responseCount": 0, "snapshotUpperSequence": 0, "collectionId": null, "acceptedFrom": null, "acceptedTo": null, "schemas": [] } } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "No export in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No export in this workspace." } } } } }, "409": { "description": "Export is queued, running or failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Export is queued, running or failed." } } } } }, "410": { "description": "Export expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "collection_expired", "message": "Export expired or was revoked." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "exports:read" } }, "/v1/retention": { "post": { "operationId": "retention_run", "summary": "Run one bounded raw-response and expired-export retention batch for the workspace.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Batch result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetentionResult" }, "example": { "responsesErased": 0, "exportsRevoked": 0 } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "description": "Erases at most 1,000 due raw responses and revokes at most 1,000 expired export jobs. Repeat while either count is 1,000 to drain a backlog.", "x-required-scope": "responses:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/workspace": { "delete": { "operationId": "workspace_delete", "summary": "Erase and tombstone the current workspace account, revoke capabilities and remove export objects.", "security": [ { "managementBearer": [] } ], "responses": { "204": { "description": "Workspace content erased and all capabilities revoked." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/memberships": { "get": { "operationId": "memberships_list", "summary": "List current workspace memberships. Owner access is required.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Memberships.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMembership" } }, "example": [ { "subject": "user_2example", "role": "reader", "grantedAt": "2026-09-08T12:00:00Z" } ] } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Owner access required." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] }, "put": { "operationId": "memberships_put", "summary": "Grant or replace a workspace membership role. Owner access is required.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipInput" }, "example": { "subject": "user_2example", "role": "reader" } } } }, "responses": { "204": { "description": "Membership saved." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Owner access required." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/memberships/revoke": { "post": { "operationId": "memberships_revoke", "summary": "Revoke a workspace membership immediately. Owner access is required.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectInput" }, "example": { "subject": "user_2example" } } } }, "responses": { "204": { "description": "Membership revoked." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Owner access required." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/service-credentials": { "get": { "operationId": "service_credentials_list", "summary": "List service credential metadata without secret values. Owner access is required.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Credential metadata.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceCredential" } }, "example": [ { "id": "10000000-0000-4000-8000-000000000005", "workspaceId": "example-workspace", "name": "Backend collector", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z", "revoked": false } ] } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] }, "post": { "operationId": "service_credentials_create", "summary": "Issue a scoped service credential. Its token is returned exactly once.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialInput" }, "example": { "name": "Backend collector", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z" } } } }, "responses": { "201": { "description": "Token is returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedServiceCredential" }, "example": { "credential": { "id": "10000000-0000-4000-8000-000000000005", "workspaceId": "example-workspace", "name": "Backend collector", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z", "revoked": false }, "token": "synthetic-example-not-a-real-credential" } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/service-credentials/{id}": { "delete": { "operationId": "service_credentials_revoke", "summary": "Irreversibly revoke a service credential.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000005" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "204": { "description": "Revoked." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing, invalid, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Not found." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write" } }, "/v1/oauth-grants": { "post": { "operationId": "oauth_grants_create", "summary": "Persist consent as a tenant, subject, client, audience and scope-bound OAuth grant.", "security": [ { "managementBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthGrantInput" }, "example": { "subject": "user_2example", "clientId": "oauth_app_2example", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z" } } } }, "responses": { "201": { "description": "Grant created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthGrant" }, "example": { "id": "10000000-0000-4000-8000-000000000006", "workspaceId": "example-workspace", "subject": "user_2example", "clientId": "oauth_app_2example", "audience": "https://api.example.com", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z", "revoked": false } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/v1/oauth-grants/{id}": { "delete": { "operationId": "oauth_grants_revoke", "summary": "Irreversibly revoke an OAuth grant for subsequent requests.", "security": [ { "managementBearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "10000000-0000-4000-8000-000000000006" }, { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "204": { "description": "Revoked." }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing, invalid, expired or revoked credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing, invalid, expired or revoked credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Not found." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "identity:write" } }, "/v1/usage": { "get": { "operationId": "usage_get", "summary": "Retrieve accepted-response counts.", "security": [ { "managementBearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "acceptedResponses": 1, "monthAcceptedResponses": 1 } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-required-scope": "usage:read", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ] } }, "/health": { "get": { "operationId": "health", "summary": "Development process health", "security": [], "responses": { "200": { "description": "Process and configured storage are healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "storage": { "type": "string", "enum": [ "development-memory", "postgres" ] } }, "required": [ "status", "storage" ], "additionalProperties": false } } } }, "500": { "description": "Configured storage health check failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Configured storage health check failed." } } } } } }, "x-interface-exempt": true } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "oauth_resource_discovery", "summary": "Discover the configured OAuth resource and authorization server.", "security": [], "x-interface-exempt": true, "responses": { "200": { "description": "Configured OAuth resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthScope" } } }, "required": [ "resource", "authorization_servers", "bearer_methods_supported", "scopes_supported" ], "additionalProperties": false } } } }, "404": { "description": "OAuth is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "OAuth is not configured." } } } } } } }, "options": { "operationId": "oauth_resource_discovery_preflight", "summary": "Preflight browser access to OAuth protected-resource metadata.", "security": [], "x-interface-exempt": true, "responses": { "204": { "description": "CORS preflight accepted." } } } }, "/internal/metrics": { "get": { "operationId": "internal_metrics", "summary": "Read private Prometheus metrics.", "security": [ { "monitorBearer": [] } ], "x-interface-exempt": true, "responses": { "200": { "description": "Prometheus text; no tenant IDs, request payloads or tokens.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing/incorrect monitor secret; empty body." }, "404": { "description": "Monitoring disabled; empty body." } } } }, "/v1/webhook-endpoints": { "post": { "operationId": "webhook_endpoints_create", "summary": "Creates disabled. Install the returned signing secret on your receiver, then explicitly enable. An identical idempotency retry reconstructs the original generation.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "201": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCredential" }, "example": { "endpoint": { "id": "10000000-0000-4000-8000-000000000041", "url": "https://hooks.customer.com/likerts", "eventTypes": [ "response.accepted" ], "enabled": false, "revoked": false, "keyId": "10000000-0000-4000-8000-000000000042", "createdAt": "2026-09-09T00:00:00Z" }, "signingSecret": "whsec_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "413": { "description": "Webhook operation error (HTTP 413).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Webhook operation could not be completed." } } } } }, "415": { "description": "Webhook operation error (HTTP 415).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" }, "example": { "idempotencyKey": "webhook-create-001", "url": "https://hooks.customer.com/likerts" } } } }, "description": "Creates a disabled response.accepted subscription. Install the returned signing secret on your receiver, then explicitly enable it. An identical idempotency retry reconstructs the original generation." }, "get": { "operationId": "webhook_endpoints_list", "summary": "Lists up to 100 workspace endpoints, including revoked entries. Signing secrets are never listed.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "example": [ { "id": "10000000-0000-4000-8000-000000000041", "url": "https://hooks.customer.com/likerts", "eventTypes": [ "response.accepted" ], "enabled": false, "revoked": false, "keyId": "10000000-0000-4000-8000-000000000042", "createdAt": "2026-09-09T00:00:00Z" } ] } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "description": "Lists up to 100 workspace endpoints, including revoked entries. Signing secrets are never listed." } }, "/v1/webhook-endpoints/{id}": { "patch": { "operationId": "webhook_endpoints_update", "summary": "Enable only after configuring verification. Use enabled:false to pause, or revoke:true to permanently cancel queued deliveries; an in-flight HTTP request cannot be recalled.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "id": "10000000-0000-4000-8000-000000000041", "url": "https://hooks.customer.com/likerts", "eventTypes": [ "response.accepted" ], "enabled": true, "revoked": false, "keyId": "10000000-0000-4000-8000-000000000042", "createdAt": "2026-09-09T00:00:00Z" } } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "413": { "description": "Webhook operation error (HTTP 413).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Webhook operation could not be completed." } } } } }, "415": { "description": "Webhook operation error (HTTP 415).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" }, "example": { "enabled": true } } } }, "description": "Enable only after configuring verification. Use enabled:false to pause, or revoke:true to permanently cancel queued deliveries; an in-flight HTTP request cannot be recalled." } }, "/v1/webhook-endpoints/{id}/rotate-key": { "post": { "operationId": "webhook_endpoints_rotate", "summary": "Install the new generation and retain the old receiver secret for five minutes. New claims use the new generation; identical rotation retries return the original protected result.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCredential" }, "example": { "endpoint": { "id": "10000000-0000-4000-8000-000000000041", "url": "https://hooks.customer.com/likerts", "eventTypes": [ "response.accepted" ], "enabled": false, "revoked": false, "keyId": "10000000-0000-4000-8000-000000000045", "createdAt": "2026-09-09T00:00:00Z" }, "signingSecret": "whsec_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "413": { "description": "Webhook operation error (HTTP 413).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Webhook operation could not be completed." } } } } }, "415": { "description": "Webhook operation error (HTTP 415).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOperationInput" }, "example": { "idempotencyKey": "webhook-rotate-001" } } } }, "description": "Install the new generation and retain the old receiver secret for five minutes. New claims use the new generation; identical rotation retries return the original protected result." } }, "/v1/webhook-deliveries": { "get": { "operationId": "webhook_deliveries_list", "summary": "Inspect delivery status. Continue with after equal to the last returned UUID for a stable ordering of existing rows; this operational list is not a response snapshot.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "query", "name": "endpointId", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "example": [ { "id": "10000000-0000-4000-8000-000000000043", "endpointId": "10000000-0000-4000-8000-000000000041", "eventId": "10000000-0000-4000-8000-000000000044", "status": "failed", "attempts": 7, "replayCount": 0, "nextAttemptAt": "2026-09-10T00:00:00Z", "lastStatus": 503, "failureCode": "attempts_exhausted", "expiresAt": "2026-09-16T00:00:00Z" } ] } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "description": "Inspect delivery status. Continue with after equal to the last returned UUID for a stable ordering of existing rows; this operational list is not a response snapshot." } }, "/v1/webhook-deliveries/{id}": { "get": { "operationId": "webhook_deliveries_get", "summary": "Read attempts, retry time and fixed failure code. Receiver bodies and survey answers are never exposed through delivery status.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:read", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "example": { "id": "10000000-0000-4000-8000-000000000043", "endpointId": "10000000-0000-4000-8000-000000000041", "eventId": "10000000-0000-4000-8000-000000000044", "status": "failed", "attempts": 7, "replayCount": 0, "nextAttemptAt": "2026-09-10T00:00:00Z", "lastStatus": 503, "failureCode": "attempts_exhausted", "expiresAt": "2026-09-16T00:00:00Z" } } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "description": "Read attempts, retry time and fixed failure code. Receiver bodies and survey answers are never exposed through delivery status." } }, "/v1/webhook-deliveries/{id}/replay": { "post": { "operationId": "webhook_deliveries_replay", "summary": "Requeue a completed or failed delivery before seven-day expiry, up to three times. The event ID remains unchanged; receivers deduplicate business processing by that ID.", "security": [ { "managementBearer": [] } ], "x-required-scope": "webhooks:write", "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": false, "description": "Required for human OAuth access; service credentials are already workspace-bound.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook operation succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "example": { "id": "10000000-0000-4000-8000-000000000043", "endpointId": "10000000-0000-4000-8000-000000000041", "eventId": "10000000-0000-4000-8000-000000000044", "status": "queued", "attempts": 0, "replayCount": 1, "nextAttemptAt": "2026-09-10T00:00:00Z", "lastStatus": null, "failureCode": null, "expiresAt": "2026-09-16T00:00:00Z" } } } }, "400": { "description": "Webhook operation error (HTTP 400).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Webhook operation could not be completed." } } } } }, "401": { "description": "Webhook operation error (HTTP 401).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Webhook operation could not be completed." } } } } }, "403": { "description": "Webhook operation error (HTTP 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Webhook operation could not be completed." } } } } }, "404": { "description": "Webhook operation error (HTTP 404).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Webhook operation could not be completed." } } } } }, "409": { "description": "Webhook operation error (HTTP 409).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Webhook operation could not be completed." } } } } }, "410": { "description": "Webhook operation error (HTTP 410).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhook_revoked", "message": "Webhook operation could not be completed." } } } } }, "413": { "description": "Webhook operation error (HTTP 413).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "Webhook operation could not be completed." } } } } }, "415": { "description": "Webhook operation error (HTTP 415).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Webhook operation could not be completed." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Webhook operation error (HTTP 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Webhook operation could not be completed." } } } } }, "503": { "description": "Durable response webhooks are not configured. Request admission can also be unavailable; fail closed and honor Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "webhooks_unavailable", "message": "Webhook operation could not be completed." } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookOperationInput" }, "example": { "idempotencyKey": "webhook-replay-001" } } } }, "description": "Requeue a completed or failed delivery before seven-day expiry, up to three times. The event ID remains unchanged; receivers deduplicate business processing by that ID." } }, "/v1/browser/bootstrap": { "post": { "operationId": "browser_bootstrap", "summary": "Create or return the signed-in principal\u2019s one stable personal workspace and current usage.", "description": "Uses a verified first-party Clerk session. Creation atomically adds owner membership and the fixed onboarding grant once. Replay requires live membership and never restores revoked ownership.", "security": [ { "browserSessionBearer": [] } ], "responses": { "200": { "description": "Existing active personal workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserBootstrap" } } } }, "201": { "description": "Personal workspace created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserBootstrap" } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Missing/invalid bearer credential, including wrong collection credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing/invalid bearer credential, including wrong collection credential." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-interface-exempt": true } }, "/v1/browser/service-credentials": { "get": { "operationId": "browser_service_credentials_list", "summary": "List scoped agent credentials as the signed-in workspace owner.", "security": [ { "browserSessionBearer": [] } ], "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Credential metadata; bearer tokens are never returned.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceCredential" } } } } }, "401": { "description": "Invalid browser session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-interface-exempt": true }, "post": { "operationId": "browser_service_credentials_create", "summary": "Create a scoped agent credential as the signed-in workspace owner; return its token once.", "security": [ { "browserSessionBearer": [] } ], "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialInput" } } } }, "responses": { "201": { "description": "Credential created; token returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuedServiceCredential" } } } }, "400": { "description": "Invalid credential request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid browser session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-interface-exempt": true } }, "/v1/browser/service-credentials/{id}": { "delete": { "operationId": "browser_service_credentials_revoke", "summary": "Irreversibly revoke an agent credential as the signed-in workspace owner.", "security": [ { "browserSessionBearer": [] } ], "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Credential revoked." }, "400": { "description": "Invalid credential identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid browser session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Owner access required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Credential not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-interface-exempt": true } }, "/v1/browser/oauth-grants": { "post": { "operationId": "browser_oauth_grants_create", "summary": "Approve one registered OAuth client and reviewed scopes as the current workspace owner.", "description": "This explicit browser action creates a maximum 30-day internal grant. No automatic first-use grant exists.", "security": [ { "browserSessionBearer": [] } ], "parameters": [ { "in": "header", "name": "X-Likerts-Workspace", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserOAuthApprovalInput" } } } }, "responses": { "201": { "description": "Grant created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthGrant" }, "example": { "id": "10000000-0000-4000-8000-000000000006", "workspaceId": "example-workspace", "subject": "user_2example", "clientId": "oauth_app_2example", "audience": "https://api.example.com", "scopes": [ "surveys:read" ], "expiresAt": "2026-09-09T12:00:00Z", "revoked": false } } } }, "400": { "description": "Invalid input, resource identifier or workspace selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "Invalid input, resource identifier or workspace selection." } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized." } } } } }, "403": { "description": "The credential scope, membership or role does not permit this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "The credential scope, membership or role does not permit this operation." } } } } }, "413": { "description": "JSON request body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "payload_too_large", "message": "JSON request body exceeds 65536 bytes." } } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unsupported_media_type", "message": "Content-Type must be application/json." } } } } }, "429": { "description": "Admission or collection rate limit reached. Honor Retry-After in seconds; admission usually returns1, the collection minute window returns60.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Request admission limit reached" } } } } }, "500": { "description": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "Internal failure; do not assume a write failed. Retry only with its original idempotency key and payload." } } } } }, "503": { "description": "Distributed request admission is temporarily unavailable. No protected handler ran; honor Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "admission_unavailable", "message": "Request admission is temporarily unavailable" } } } } } }, "x-interface-exempt": true } } }, "components": { "securitySchemes": { "managementBearer": { "type": "http", "scheme": "bearer", "description": "OIDC JWT or tenant-bound service credential. Human OAuth requests select a workspace with X-Likerts-Workspace; Likerts rechecks the token scope, durable grant and current membership. Static all-access tokens are development-only." }, "collectionBearer": { "type": "http", "scheme": "bearer", "description": "Collection token returned by collections_create. Only schema access and submission for that collection. Management credentials do not substitute." }, "monitorBearer": { "type": "http", "scheme": "bearer", "description": "Separate LIKERTS_MONITOR_TOKEN; not a management or collection credential." }, "browserSessionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Clerk session JWT", "description": "First-party browser session only. Exact issuer, audience, expiry, subject and authorized-party Origin are verified; it is not an OAuth capability token." } }, "schemas": { "Choice": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "other": { "type": "object", "properties": { "maxLength": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "maxLength" ], "additionalProperties": false }, "exclusive": { "const": true } }, "required": [ "id", "label" ], "additionalProperties": false }, "VisibilityCondition": { "type": "object", "properties": { "questionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "operator": { "type": "string", "enum": [ "equals", "not_equals", "includes", "not_includes", "answered", "not_answered" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "questionId", "operator" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "operator": { "enum": [ "answered", "not_answered" ] } } }, "then": { "not": { "required": [ "value" ] } }, "else": { "required": [ "value" ] } } ], "description": "One bounded predicate. answered/not_answered forbid value; other operators require it. equals/not_equals apply to scalar answers; includes/not_includes apply to multiple-choice selections. The backend validates reference existence, source compatibility, choice/range membership and an acyclic dependency graph. Comparison operators are false when the effective source answer is absent; answered trims strings." }, "PageBranch": { "type": "object", "properties": { "when": { "$ref": "#/components/schemas/VisibilityCondition" }, "goToPageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "required": [ "when", "goToPageId" ], "additionalProperties": false }, "SurveyPage": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questionIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/PageBranch" }, "maxItems": 20, "default": [] } }, "required": [ "id", "questionIds" ], "additionalProperties": false }, "single_choiceQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "single_choice" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" }, "minItems": 1, "maxItems": 100 }, "preset": { "const": "yes_no" }, "presentation": { "const": "dropdown" } }, "required": [ "id", "label", "type", "options" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "preset" ] }, "then": { "properties": { "options": { "minItems": 2, "maxItems": 2, "items": { "properties": { "id": { "enum": [ "yes", "no" ] } } }, "allOf": [ { "contains": { "properties": { "id": { "const": "yes" } } }, "minContains": 1, "maxContains": 1 }, { "contains": { "properties": { "id": { "const": "no" } } }, "minContains": 1, "maxContains": 1 } ] } } } } ] }, "multiple_choiceQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "multiple_choice" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" }, "minItems": 1, "maxItems": 100 }, "minSelections": { "type": "integer", "minimum": 0, "maximum": 100 }, "maxSelections": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "id", "label", "type", "options" ], "additionalProperties": false, "description": "Selection bounds must satisfy effective minimum <= maximum <= option count. Effective minimum is max(minSelections or 0, required ? 1 : 0). Default maximum is option count. Optional answers may be omitted, but a supplied array must respect the bounds. Backend enforces these related-field constraints." }, "scaleQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "scale" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "min": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "max": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "preset": { "const": "nps" }, "labels": { "type": "object", "propertyNames": { "pattern": "^(0|-[1-9][0-9]*|[1-9][0-9]*)$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "description": "Keys must be canonical integer strings within min/max; the backend enforces range membership." }, "presentation": { "const": "stars" } }, "required": [ "id", "label", "type", "min", "max" ], "additionalProperties": false, "allOf": [ { "if": { "required": [ "preset" ] }, "then": { "properties": { "min": { "const": 0 }, "max": { "const": 10 } } } } ] }, "textQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "text" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "id", "label", "type", "maxLength" ], "additionalProperties": false }, "numberQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "number" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "id", "label", "type" ], "additionalProperties": false }, "dateQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "date" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" } }, "required": [ "id", "label", "type" ], "additionalProperties": false }, "Question": { "oneOf": [ { "$ref": "#/components/schemas/single_choiceQuestion" }, { "$ref": "#/components/schemas/multiple_choiceQuestion" }, { "$ref": "#/components/schemas/scaleQuestion" }, { "$ref": "#/components/schemas/textQuestion" }, { "$ref": "#/components/schemas/numberQuestion" }, { "$ref": "#/components/schemas/dateQuestion" }, { "$ref": "#/components/schemas/rankingQuestion" }, { "$ref": "#/components/schemas/matrixQuestion" }, { "$ref": "#/components/schemas/constant_sumQuestion" } ], "description": "Question IDs must be unique within a survey; option IDs unique within each question; min must not exceed max. Backend validates these cross-field constraints. Expanded fields are permitted only on their respective types. preset, labels, minSelections or maxSelections require schemaVersion 2. visibleWhen, Other/exclusive choices or presentation require schemaVersion 3. Hidden answers are discarded before validation and persistence; hidden required questions are not required. ranking, matrix or constant_sum requires schemaVersion 5." }, "DraftInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "title", "questions" ], "additionalProperties": false, "example": { "title": "Checkout experience", "questions": [ { "id": "recommend", "type": "scale", "preset": "nps", "label": "How likely are you to recommend us?", "required": true, "min": 0, "max": 10, "labels": { "0": "Not at all likely", "10": "Extremely likely" } }, { "id": "easy", "type": "scale", "label": "Checkout was easy", "required": true, "min": 1, "max": 5, "labels": { "1": "Strongly disagree", "2": "Disagree", "3": "Neutral", "4": "Agree", "5": "Strongly agree" } }, { "id": "return", "type": "single_choice", "preset": "yes_no", "label": "Would you shop again?", "required": true, "options": [ { "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" } ] }, { "id": "improvements", "type": "multiple_choice", "label": "Choose one or two improvements", "required": true, "minSelections": 1, "maxSelections": 2, "options": [ { "id": "speed", "label": "Speed" }, { "id": "payment", "label": "Payment options" }, { "id": "navigation", "label": "Navigation" } ] } ] } }, "SurveyCreateInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S", "description": "Required by survey creation; omitted from draft update payloads." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "title", "questions", "idempotencyKey" ], "additionalProperties": false, "example": { "title": "Checkout experience", "questions": [ { "id": "recommend", "type": "scale", "preset": "nps", "label": "How likely are you to recommend us?", "required": true, "min": 0, "max": 10, "labels": { "0": "Not at all likely", "10": "Extremely likely" } }, { "id": "easy", "type": "scale", "label": "Checkout was easy", "required": true, "min": 1, "max": 5, "labels": { "1": "Strongly disagree", "2": "Disagree", "3": "Neutral", "4": "Agree", "5": "Strongly agree" } }, { "id": "return", "type": "single_choice", "preset": "yes_no", "label": "Would you shop again?", "required": true, "options": [ { "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" } ] }, { "id": "improvements", "type": "multiple_choice", "label": "Choose one or two improvements", "required": true, "minSelections": 1, "maxSelections": 2, "options": [ { "id": "speed", "label": "Speed" }, { "id": "payment", "label": "Payment options" }, { "id": "navigation", "label": "Navigation" } ] } ] } }, "Survey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "id", "revision", "title", "questions" ], "additionalProperties": false }, "SdkInstallationCapability": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "web", "react_native", "ios", "android", "flutter" ] }, "sdkVersion": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "\\S" }, "schemaVersions": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "minItems": 1, "maxItems": 16, "uniqueItems": true } }, "required": [ "target", "sdkVersion", "schemaVersions" ], "additionalProperties": false }, "SdkCapabilities": { "type": "object", "properties": { "installations": { "type": "array", "items": { "$ref": "#/components/schemas/SdkInstallationCapability" }, "minItems": 1, "maxItems": 100 } }, "required": [ "installations" ], "additionalProperties": false, "description": "Customer-declared installed SDK groups. Every group must include the published/bound survey schema version. This is a compatibility guard, not attestation." }, "Version": { "type": "object", "properties": { "surveyId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 }, "sdkCapabilities": { "$ref": "#/components/schemas/SdkCapabilities" } }, "required": [ "surveyId", "version", "title", "questions", "sdkCapabilities" ], "additionalProperties": false }, "UpdateInput": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "revision", "title", "questions" ], "additionalProperties": false }, "PublishInput": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "sdkCapabilities": { "$ref": "#/components/schemas/SdkCapabilities" } }, "required": [ "revision", "sdkCapabilities" ], "additionalProperties": false }, "CollectionInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S" }, "surveyId": { "type": "string" }, "version": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "placement": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional future expiry, at most 90 days from creation." }, "responseCap": { "type": "integer", "minimum": 1, "maximum": 9223372036854776000 }, "sdkCapabilities": { "$ref": "#/components/schemas/SdkCapabilities" } }, "required": [ "idempotencyKey", "surveyId", "version", "placement", "sdkCapabilities" ], "additionalProperties": false }, "Collection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "surveyId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "placement": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "token": { "type": "string", "description": "Opaque limited collection bearer credential; never parse its format. Returned on creation; cannot manage surveys or read responses.", "minLength": 16, "maxLength": 256 }, "accepting": { "type": "boolean" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "responseCap": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 9223372036854776000 }, "revoked": { "type": "boolean" }, "sdkCapabilities": { "$ref": "#/components/schemas/SdkCapabilities" } }, "required": [ "id", "surveyId", "version", "placement", "token", "accepting", "expiresAt", "responseCap", "revoked", "sdkCapabilities" ], "additionalProperties": false }, "CollectionSecurityInput": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "format": "uri", "description": "Exact HTTPS origin; loopback HTTP is allowed for development." } }, "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "allowedOrigins", "requestsPerMinute" ], "additionalProperties": false }, "CollectionSecurity": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid" }, "allowedOrigins": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "format": "uri" } }, "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 100000 } }, "required": [ "collectionId", "allowedOrigins", "requestsPerMinute" ], "additionalProperties": false }, "AcceptanceInput": { "type": "object", "properties": { "accepting": { "type": "boolean" }, "revoke": { "const": true } }, "minProperties": 1, "maxProperties": 1, "additionalProperties": false }, "Acceptance": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accepting": { "type": "boolean" }, "revoked": { "type": "boolean" } }, "required": [ "id", "accepting", "revoked" ], "additionalProperties": false }, "Configuration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "surveyId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "placement": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "schema": { "type": "object", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1, 2, 3, 4, 5 ], "description": "1 for legacy six-type surveys; 2 for expanded presets, labels or selection bounds; 3 for conditional visibility, Other/exclusive choices or presentation controls; 4 for pages and bounded forward branching. 5 for ranking, matrix and constant-sum questions." }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "\\S" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" }, "minItems": 1, "maxItems": 100 }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "schemaVersion", "title", "questions" ], "additionalProperties": false } }, "required": [ "id", "surveyId", "version", "placement", "schema" ], "additionalProperties": false }, "Submission": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "\\S" }, "answers": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, { "type": "object", "properties": { "selected": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "otherText": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "selected", "otherText" ], "additionalProperties": false }, { "$ref": "#/components/schemas/MatrixSingleAnswer" }, { "$ref": "#/components/schemas/MatrixMultipleAnswer" }, { "$ref": "#/components/schemas/ConstantSumAnswer" } ] }, "description": "Question-ID keyed answers. Legacy and schema-v3 choice answers retain their documented wire types. Ranking is a complete option-ID permutation; matrix is a row-ID map to a column ID or nonempty column-ID array; constant_sum is an exact item-ID map to nonnegative integers totaling the configured total. The backend validates dynamic membership, sums, requiredness, routes and visibility." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Untrusted caller metadata; compact serialized JSON must be at most 4096 bytes.", "default": {} } }, "required": [ "idempotencyKey", "answers" ], "additionalProperties": false, "example": { "idempotencyKey": "fixture-submission-0001", "answers": { "rating": 4, "reason": "speed", "improvements": [ "payment" ], "comment": "Easy to use", "minutes": 2.5, "visitDate": "2026-09-06" }, "metadata": { "placement": "checkout-success" } } }, "Receipt": { "type": "object", "properties": { "responseId": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid" }, "accepted": { "const": true } }, "required": [ "responseId", "collectionId", "accepted" ], "additionalProperties": false, "description": "Immutable acknowledgement of one accepted response. Likerts does not meter or charge responses." }, "Response": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/Receipt" }, "answers": { "type": "object", "additionalProperties": true, "description": "Question-ID keyed answers. Strings for text/date/single_choice; unique option-ID string arrays for multiple_choice; numbers for number; integers for scale. Required questions must be answered, unknown IDs rejected, bounds/options/date validity checked against published schema. Optional answers are omitted, not null." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Untrusted caller metadata; compact serialized JSON must be at most 4096 bytes." }, "acceptedAt": { "type": "string", "format": "date-time", "description": "Server acceptance time in UTC." } }, "required": [ "receipt", "answers", "metadata", "acceptedAt" ], "additionalProperties": false }, "ResponsePage": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/Response" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque continuation cursor; null when the snapshot is exhausted." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "ExportInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "collectionId": { "type": "string", "format": "uuid" }, "acceptedFrom": { "type": "string", "format": "date-time" }, "acceptedTo": { "type": "string", "format": "date-time" } }, "required": [ "idempotencyKey", "format" ], "additionalProperties": false, "description": "Optional collection and acceptance-time filters use the same inclusive acceptedFrom and exclusive acceptedTo semantics as response retrieval." }, "ExportSchema": { "type": "object", "properties": { "surveyId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "schemaVersion": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "minItems": 1, "maxItems": 50 } }, "required": [ "surveyId", "version", "schemaVersion", "title", "questions" ], "additionalProperties": false }, "ExportManifest": { "type": "object", "properties": { "formatVersion": { "const": 1 }, "responseCount": { "type": "integer", "minimum": 0 }, "snapshotUpperSequence": { "type": "integer", "minimum": 0 }, "collectionId": { "type": [ "string", "null" ], "format": "uuid" }, "acceptedFrom": { "type": [ "string", "null" ], "format": "date-time" }, "acceptedTo": { "type": [ "string", "null" ], "format": "date-time" }, "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/ExportSchema" } } }, "required": [ "formatVersion", "responseCount", "snapshotUpperSequence", "collectionId", "acceptedFrom", "acceptedTo", "schemas" ], "additionalProperties": false }, "ExportJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "responseCount": { "type": [ "integer", "null" ], "minimum": 0 }, "contentSha256": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$" }, "manifest": { "oneOf": [ { "$ref": "#/components/schemas/ExportManifest" }, { "type": "null" } ] }, "errorCode": { "type": [ "string", "null" ] } }, "required": [ "id", "format", "status", "createdAt", "expiresAt", "responseCount", "contentSha256", "manifest", "errorCode" ], "additionalProperties": false }, "ExportDownload": { "type": "object", "properties": { "fileName": { "type": "string" }, "contentType": { "type": "string", "enum": [ "text/csv", "application/json" ] }, "contentBase64": { "type": "string", "contentEncoding": "base64" }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "manifest": { "$ref": "#/components/schemas/ExportManifest" } }, "required": [ "fileName", "contentType", "contentBase64", "contentSha256", "manifest" ], "additionalProperties": false }, "RetentionResult": { "type": "object", "properties": { "responsesErased": { "type": "integer", "minimum": 0, "maximum": 1000 }, "exportsRevoked": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "responsesErased", "exportsRevoked" ], "additionalProperties": false }, "Role": { "type": "string", "enum": [ "owner", "editor", "reader" ] }, "WorkspaceMembership": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "$ref": "#/components/schemas/Role" }, "grantedAt": { "type": "string", "format": "date-time" } }, "required": [ "subject", "role", "grantedAt" ], "additionalProperties": false }, "MembershipInput": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "$ref": "#/components/schemas/Role" } }, "required": [ "subject", "role" ], "additionalProperties": false }, "SubjectInput": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "subject" ], "additionalProperties": false }, "OAuthScope": { "type": "string", "enum": [ "surveys:read", "surveys:write", "collections:write", "responses:read", "responses:write", "usage:read", "exports:read", "exports:write", "identity:write", "webhooks:read", "webhooks:write" ] }, "CredentialInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OAuthScope" } }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "name", "scopes", "expiresAt" ], "additionalProperties": false }, "ServiceCredential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthScope" } }, "expiresAt": { "type": "string", "format": "date-time" }, "revoked": { "type": "boolean" } }, "required": [ "id", "workspaceId", "name", "scopes", "expiresAt", "revoked" ], "additionalProperties": false }, "IssuedServiceCredential": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/ServiceCredential" }, "token": { "type": "string", "minLength": 1 } }, "required": [ "credential", "token" ], "additionalProperties": false }, "OAuthGrantInput": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 255 }, "clientId": { "type": "string", "minLength": 1, "maxLength": 255 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OAuthScope" } }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "subject", "clientId", "scopes", "expiresAt" ], "additionalProperties": false }, "OAuthGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string" }, "subject": { "type": "string" }, "clientId": { "type": "string" }, "audience": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthScope" } }, "expiresAt": { "type": "string", "format": "date-time" }, "revoked": { "type": "boolean" } }, "required": [ "id", "workspaceId", "subject", "clientId", "audience", "scopes", "expiresAt", "revoked" ], "additionalProperties": false }, "RefundInput": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "amountCents", "reason", "idempotencyKey" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "acceptedResponses": { "type": "integer", "minimum": 0, "description": "Lifetime accepted response count." }, "monthAcceptedResponses": { "type": "integer", "minimum": 0, "description": "Accepted response count in the current UTC month." } }, "required": [ "acceptedResponses", "monthAcceptedResponses" ], "additionalProperties": false, "description": "Response counts for observability. These values never gate acceptance or create a charge." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "collection_closed", "collection_capacity", "export_not_ready", "webhook_capacity", "collection_expired", "collection_revoked", "export_expired", "export_revoked", "receipt_expired", "webhook_expired", "webhook_revoked", "payload_too_large", "unsupported_media_type", "rate_limited", "internal_error", "webhooks_unavailable", "admission_unavailable", "erasure_source_fenced" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "ToolError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "code", "message", "status", "operation" ], "properties": { "code": { "const": "http_error" }, "message": { "type": "string" }, "status": { "type": "integer", "minimum": 100, "maximum": 599 }, "operation": { "type": "string", "enum": [ "surveys_create", "surveys_list", "surveys_update", "surveys_publish", "collections_create", "collections_update", "collections_security_update", "collections_get", "responses_submit", "responses_list", "responses_delete", "exports_create", "exports_get", "exports_download", "exports_revoke", "retention_run", "workspace_delete", "memberships_list", "memberships_put", "memberships_revoke", "service_credentials_list", "service_credentials_create", "service_credentials_revoke", "oauth_grants_create", "oauth_grants_revoke", "usage_get", "webhook_endpoints_create", "webhook_endpoints_list", "webhook_endpoints_update", "webhook_endpoints_rotate", "webhook_deliveries_list", "webhook_deliveries_get", "webhook_deliveries_replay" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "enum": [ "unknown_capability", "invalid_request", "invalid_response", "request_failed" ] }, "message": { "type": "string" } } } ] } } }, "PromptItem": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" } }, "required": [ "id", "label" ], "additionalProperties": false }, "rankingQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "ranking" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" }, "minItems": 2, "maxItems": 50, "uniqueItems": true } }, "required": [ "id", "label", "type", "options" ], "additionalProperties": false }, "matrixQuestion": { "type": "object", "description": "rows \u00d7 columns is limited to 200; semantic validation enforces unique IDs and plain columns without Other/exclusive.", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "matrix" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "matrixMode": { "type": "string", "enum": [ "single", "multiple" ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/PromptItem" }, "minItems": 1, "maxItems": 50 }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" }, "minItems": 2, "maxItems": 20 } }, "required": [ "id", "label", "type", "matrixMode", "rows", "columns" ], "additionalProperties": false }, "constant_sumQuestion": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "type": { "const": "constant_sum" }, "required": { "type": "boolean", "default": false }, "visibleWhen": { "$ref": "#/components/schemas/VisibilityCondition" }, "total": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PromptItem" }, "minItems": 2, "maxItems": 50 } }, "required": [ "id", "label", "type", "total", "items" ], "additionalProperties": false }, "RankingAnswer": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "minItems": 2, "maxItems": 50, "uniqueItems": true }, "MatrixSingleAnswer": { "type": "object", "minProperties": 1, "maxProperties": 50, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "MatrixMultipleAnswer": { "type": "object", "minProperties": 1, "maxProperties": 50, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "minItems": 1, "maxItems": 20, "uniqueItems": true } }, "ConstantSumAnswer": { "type": "object", "minProperties": 2, "maxProperties": 50, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "enabled": { "type": "boolean" }, "revoked": { "type": "boolean" }, "keyId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "eventTypes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "response.accepted" ] }, "description": "Immutable event subscriptions. Community Edition supports response.accepted." } }, "required": [ "id", "url", "enabled", "revoked", "keyId", "createdAt", "eventTypes" ], "additionalProperties": false }, "WebhookCredential": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "signingSecret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$" } }, "required": [ "endpoint", "signingSecret" ], "additionalProperties": false }, "WebhookEndpointInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }, "eventTypes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "response.accepted" ] }, "description": "Immutable event subscriptions. Community Edition supports response.accepted.", "default": [ "response.accepted" ] } }, "required": [ "idempotencyKey", "url" ], "additionalProperties": false }, "WebhookEndpointUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "revoke": { "const": true } }, "required": [], "additionalProperties": false, "minProperties": 1, "not": { "required": [ "enabled", "revoke" ], "properties": { "enabled": { "const": true }, "revoke": { "const": true } } }, "description": "Pause, enable or permanently revoke. URL and event subscriptions are immutable." }, "WebhookOperationInput": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "idempotencyKey" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "endpointId": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "status": { "enum": [ "queued", "running", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 7 }, "replayCount": { "type": "integer", "minimum": 0, "maximum": 3 }, "nextAttemptAt": { "type": "string", "format": "date-time" }, "lastStatus": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpointId", "eventId", "status", "attempts", "replayCount", "nextAttemptAt", "lastStatus", "failureCode", "expiresAt" ], "additionalProperties": false }, "WebhookResponseEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "response.accepted" }, "eventVersion": { "const": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "responseId": { "type": "string", "format": "uuid" }, "collectionId": { "type": "string", "format": "uuid" }, "surveyId": { "type": "string", "format": "uuid" }, "surveyVersion": { "type": "integer", "minimum": 1 } }, "required": [ "responseId", "collectionId", "surveyId", "surveyVersion" ], "additionalProperties": false } }, "required": [ "id", "type", "eventVersion", "createdAt", "data" ], "additionalProperties": false }, "BrowserBootstrap": { "type": "object", "additionalProperties": false, "required": [ "workspaceId", "created", "usage" ], "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[A-Za-z0-9_-]{24}$" }, "created": { "type": "boolean" }, "usage": { "$ref": "#/components/schemas/Usage" } } }, "BrowserOAuthApprovalInput": { "type": "object", "additionalProperties": false, "required": [ "clientId", "scopes" ], "properties": { "clientId": { "type": "string", "minLength": 1, "maxLength": 255 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "type": "string" } } } } } } }