{ "openapi": "3.1.0", "info": { "title": "Neatlogs Public API", "version": "0.1.0", "description": "Filtered public API specification for customer-facing /api/v1/public/* endpoints only." }, "servers": [ { "url": "https://app.neatlogs.com", "description": "NeatLogs cloud Public API" } ], "tags": [ { "name": "access" }, { "name": "account" }, { "name": "alerts" }, { "name": "analytics" }, { "name": "api-keys" }, { "name": "audit" }, { "name": "batches" }, { "name": "billing" }, { "name": "bindings" }, { "name": "coding-tools" }, { "name": "comments" }, { "name": "configuration" }, { "name": "credential-migrations" }, { "name": "credentials" }, { "name": "deletion" }, { "name": "detections" }, { "name": "evaluations" }, { "name": "evaluators" }, { "name": "export" }, { "name": "feedback" }, { "name": "guest-review" }, { "name": "imports" }, { "name": "ingest-credentials" }, { "name": "integrations" }, { "name": "invitations" }, { "name": "issues" }, { "name": "mcp" }, { "name": "members" }, { "name": "notifications" }, { "name": "oauth" }, { "name": "organizations" }, { "name": "projects" }, { "name": "prompts" }, { "name": "public" }, { "name": "roles" }, { "name": "saved-filters" }, { "name": "search" }, { "name": "service-accounts" }, { "name": "sessions" }, { "name": "sharing" }, { "name": "skills" }, { "name": "spans" }, { "name": "suggestions" }, { "name": "tokens" }, { "name": "traces" }, { "name": "webhooks" } ], "components": { "headers": { "PublicApiLegacyRateLimitLimit": { "description": "Effective request ceiling for the current window", "schema": { "minimum": 1, "type": "integer" } }, "PublicApiLegacyRateLimitRemaining": { "description": "Requests remaining in the current window", "schema": { "minimum": 0, "type": "integer" } }, "PublicApiRateLimitDegraded": { "description": "Whether bounded emergency enforcement is active", "schema": { "enum": [ "true", "false" ], "type": "string" } }, "PublicApiRateLimitLimit": { "description": "Effective request ceiling for the current window", "schema": { "minimum": 1, "type": "integer" } }, "PublicApiRateLimitPolicy": { "description": "Applied pre-authentication or authenticated rate class", "schema": { "type": "string" } }, "PublicApiRateLimitRemaining": { "description": "Requests remaining in the current window", "schema": { "minimum": 0, "type": "integer" } }, "PublicApiRateLimitReset": { "description": "Unix timestamp in seconds when the current window resets", "schema": { "minimum": 0, "type": "integer" } }, "PublicApiRateLimitResetAfter": { "description": "Whole seconds until the current window resets", "schema": { "minimum": 1, "type": "integer" } }, "PublicApiRateLimitVersion": { "description": "NeatLogs rate-limit contract version", "schema": { "const": "1", "type": "string" } }, "PublicApiRequestId": { "description": "Server-owned request correlation identifier", "schema": { "pattern": "^req_[a-f0-9]{32}$", "type": "string" } }, "PublicApiRetryAfter": { "description": "Whole seconds until the client should retry", "schema": { "minimum": 1, "type": "integer" } }, "PublicApiWwwAuthenticate": { "description": "Bearer authentication challenge", "schema": { "type": "string" } } }, "schemas": { "PublicApiProblem": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 96, "pattern": "^[A-Z][A-Z0-9_]*$" }, "detail": { "type": "string", "minLength": 1, "maxLength": 512 }, "errors": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 64, "pattern": "^[a-z0-9_]+$" }, "message": { "type": "string", "minLength": 1, "maxLength": 160 }, "path": { "type": "string", "maxLength": 160 } }, "required": [ "code", "message", "path" ], "additionalProperties": false } }, "instance": { "type": "string", "maxLength": 2048, "pattern": "^\\/[aA][pP][iI]\\/[vV][0-9]+\\/[pP][uU][bB][lL][iI][cC](?:\\/[^?#\\r\\n]*)?$" }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "retryable": { "type": "boolean" }, "status": { "enum": [ 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503 ], "type": "integer" }, "title": { "type": "string", "minLength": 1, "maxLength": 128 }, "type": { "type": "string", "pattern": "^urn:neatlogs:problem:[a-z0-9]+(?:-[a-z0-9]+)*$" } }, "required": [ "code", "detail", "instance", "requestId", "retryable", "status", "title", "type" ], "additionalProperties": false }, "PublicDetectionIssueSemanticsInput": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "detector-issue-semantics-v1" }, "polarity": { "type": "string", "enum": [ "problem", "healthy", "informational", "unknown" ] }, "authority": { "default": "none", "type": "string", "enum": [ "none", "project_authoritative" ] }, "truth_role": { "type": "string", "minLength": 1, "maxLength": 100 }, "contract_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "contract_version": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "schema_version", "polarity" ], "additionalProperties": false }, "PublicDetectionIssueSemanticsOutput": { "type": "object", "properties": { "schema_version": { "type": "string", "const": "detector-issue-semantics-v1" }, "polarity": { "type": "string", "enum": [ "problem", "healthy", "informational", "unknown" ] }, "authority": { "default": "none", "type": "string", "enum": [ "none", "project_authoritative" ] }, "truth_role": { "type": "string", "minLength": 1, "maxLength": 100 }, "contract_id": { "type": "string", "minLength": 1, "maxLength": 256 }, "contract_version": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "schema_version", "polarity", "authority" ], "additionalProperties": false }, "PublicDetectionSummary": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "enum": [ "classifier", "regex", "conditional", "pii", "custom_trained", "code", "trace_rules", "decision" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt" ], "additionalProperties": false }, "PublicSavedFilter": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "filters": { "description": "At most 100 total nodes and 262144 UTF-8 bytes after PostgreSQL jsonb normalization.", "items": { "$ref": "#/components/schemas/PublicSavedFilterNode8" }, "maxItems": 100, "type": "array" } }, "required": [ "createdAt", "filters", "id", "name", "updatedAt" ], "type": "object" }, "PublicSavedFilterCreateRequest": { "additionalProperties": false, "properties": { "filters": { "description": "At most 100 total nodes and 262144 UTF-8 bytes after PostgreSQL jsonb normalization.", "items": { "$ref": "#/components/schemas/PublicSavedFilterNode8" }, "maxItems": 100, "type": "array" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "filters", "name" ], "type": "object" }, "PublicSavedFilterDeleteRequest": { "additionalProperties": false, "properties": { "confirmation": { "format": "uuid", "type": "string" } }, "required": [ "confirmation" ], "type": "object" }, "PublicSavedFilterEnvelope": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PublicSavedFilter" }, "requestId": { "pattern": "^req_[a-f0-9]{32}$", "type": "string" }, "success": { "const": true, "type": "boolean" } }, "required": [ "data", "requestId", "success" ], "type": "object" }, "PublicSavedFilterGroup1": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterRule" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup2": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode1" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup3": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode2" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup4": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode3" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup5": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode4" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup6": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode5" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup7": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode6" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterGroup8": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "logicalOperator": { "enum": [ "And", "Or" ], "type": "string" }, "rules": { "items": { "$ref": "#/components/schemas/PublicSavedFilterNode7" }, "maxItems": 100, "type": "array" }, "type": { "const": "group", "type": "string" } }, "required": [ "id", "logicalOperator", "rules", "type" ], "type": "object" }, "PublicSavedFilterJsonDepth1": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterJsonScalar" }, { "items": { "$ref": "#/components/schemas/PublicSavedFilterJsonScalar" }, "maxItems": 100, "type": "array" }, { "additionalProperties": { "$ref": "#/components/schemas/PublicSavedFilterJsonScalar" }, "maxProperties": 50, "propertyNames": { "maxLength": 255, "minLength": 1, "type": "string" }, "type": "object" } ] }, "PublicSavedFilterJsonDepth2": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterJsonScalar" }, { "items": { "$ref": "#/components/schemas/PublicSavedFilterJsonDepth1" }, "maxItems": 100, "type": "array" }, { "additionalProperties": { "$ref": "#/components/schemas/PublicSavedFilterJsonDepth1" }, "maxProperties": 50, "propertyNames": { "maxLength": 255, "minLength": 1, "type": "string" }, "type": "object" } ] }, "PublicSavedFilterJsonScalar": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "PublicSavedFilterList": { "additionalProperties": false, "properties": { "page": { "additionalProperties": false, "properties": { "hasMore": { "type": "boolean" }, "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "nextCursor": { "anyOf": [ { "maxLength": 1024, "minLength": 1, "type": "string" }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "type": "object" }, "savedFilters": { "items": { "$ref": "#/components/schemas/PublicSavedFilterSummary" }, "maxItems": 100, "type": "array" } }, "required": [ "page", "savedFilters" ], "type": "object" }, "PublicSavedFilterListEnvelope": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/PublicSavedFilterList" }, "requestId": { "pattern": "^req_[a-f0-9]{32}$", "type": "string" }, "success": { "const": true, "type": "boolean" } }, "required": [ "data", "requestId", "success" ], "type": "object" }, "PublicSavedFilterNode1": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup1" } ] }, "PublicSavedFilterNode2": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup2" } ] }, "PublicSavedFilterNode3": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup3" } ] }, "PublicSavedFilterNode4": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup4" } ] }, "PublicSavedFilterNode5": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup5" } ] }, "PublicSavedFilterNode6": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup6" } ] }, "PublicSavedFilterNode7": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup7" } ] }, "PublicSavedFilterNode8": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterRule" }, { "$ref": "#/components/schemas/PublicSavedFilterGroup8" } ] }, "PublicSavedFilterRule": { "additionalProperties": false, "properties": { "field": { "maxLength": 255, "minLength": 1, "type": "string" }, "id": { "maxLength": 128, "minLength": 1, "type": "string" }, "label": { "maxLength": 255, "type": "string" }, "operator": { "enum": [ "is", "is_not", "contains", "contains_any", "not_contains", "starts_with", "ends_with", "greater_than", "less_than", "is_empty", "is_not_empty", "is_within_range", "is_any_of", "is_not_any_of", "equals", "not_equals", "is_exactly" ], "type": "string" }, "value": { "$ref": "#/components/schemas/PublicSavedFilterValue" } }, "required": [ "field", "id", "operator", "value" ], "type": "object" }, "PublicSavedFilterSummary": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "type": "object" }, "PublicSavedFilterUpdateRequest": { "additionalProperties": false, "properties": { "filters": { "description": "At most 100 total nodes and 262144 UTF-8 bytes after PostgreSQL jsonb normalization.", "items": { "$ref": "#/components/schemas/PublicSavedFilterNode8" }, "maxItems": 100, "type": "array" }, "name": { "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [], "type": "object", "minProperties": 1 }, "PublicSavedFilterValue": { "anyOf": [ { "$ref": "#/components/schemas/PublicSavedFilterJsonScalar" }, { "items": { "$ref": "#/components/schemas/PublicSavedFilterJsonDepth2" }, "maxItems": 100, "type": "array" }, { "additionalProperties": { "$ref": "#/components/schemas/PublicSavedFilterJsonDepth2" }, "maxProperties": 50, "propertyNames": { "maxLength": 255, "minLength": 1, "type": "string" }, "type": "object" } ] } }, "securitySchemes": { "GuestTokenAuth": { "type": "http", "scheme": "neatlogsguest", "description": "Guest review token sent only as Authorization: NeatLogsGuest ." }, "PublicApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Public API key scoped to one project/org." }, "PublicApiLegacyBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "NeatLogs public API key", "description": "Legacy Authorization: Bearer carrier for the same public API key. This is not OAuth 2.0 or a service token." }, "ServiceAccountBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "NeatLogs service-account token", "description": "Service-account token using the nlsa_ prefix. Send only as Authorization: Bearer; each operation declares its required context parameters." }, "OAuth2": { "type": "oauth2", "description": "First-party NeatLogs OAuth access tokens use the nloa_ prefix and Authorization: Bearer only; each operation declares its required context parameters.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.neatlogs.com/oauth/authorize", "tokenUrl": "https://app.neatlogs.com/oauth/token", "scopes": { "context:read": "context:read", "project:write": "project:write", "organization:read": "organization:read", "organization:write": "organization:write", "billing:read": "billing:read", "profile:read": "profile:read", "profile:write": "profile:write", "observability:read": "observability:read", "observability:write": "observability:write", "evaluation:read": "evaluation:read", "evaluation:write": "evaluation:write", "configuration:read": "configuration:read", "configuration:write": "configuration:write", "sharing:read": "sharing:read", "sharing:write": "sharing:write", "access:read": "access:read", "access:write": "access:write", "offline_access": "offline_access" } } }, "x-device-authorization-url": "https://app.neatlogs.com/oauth/device/code" } } }, "paths": { "/api/v1/public/account/profile": { "get": { "tags": [ "public", "account" ], "summary": "Get current public profile", "description": "List or read account profile.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_account_profile", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Current public profile", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "avatarConfigured": { "type": "boolean" }, "bio": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "uri" }, { "type": "null" } ] } }, "required": [ "avatarConfigured", "bio", "companyName", "language", "name", "timezone", "websiteUrl" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "profile:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "account" ], "summary": "Update current public profile", "description": "Partially update account profile.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_account_profile", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Current public profile after update", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "avatarConfigured": { "type": "boolean" }, "bio": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "websiteUrl": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "uri" }, { "type": "null" } ] } }, "required": [ "avatarConfigured", "bio", "companyName", "language", "name", "timezone", "websiteUrl" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "profile:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "bio": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/alert-history": { "get": { "tags": [ "public", "alerts" ], "summary": "List alert fire history", "description": "List or read public alert-history.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_alert_history", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert fire history", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alertHistory": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "channelsDelivered": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "in_app", "slack", "email", "webhook" ] } }, "count": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "firedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "investigationTarget": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "trace" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "traceId" ], "additionalProperties": false }, { "type": "object", "properties": { "detectionSlugs": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "kind": { "type": "string", "const": "trace_search" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "detectionSlugs", "from", "kind", "to" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "isFollowup": { "type": "boolean" }, "ruleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ruleName": { "type": "string", "minLength": 1, "maxLength": 255 }, "sampleTraceIds": { "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sampleTraceIdsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sampleTraceIdsTruncated": { "type": "boolean" }, "suppressedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "threshold": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "channelsDelivered", "count", "detectionName", "firedAt", "id", "investigationTarget", "isFollowup", "ruleId", "ruleName", "sampleTraceIds", "sampleTraceIdsTotal", "sampleTraceIdsTruncated", "suppressedCount", "threshold", "windowMinutes" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "alertHistory", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "alertRuleId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId query parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "endTime query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "startTime query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/alert-rules": { "get": { "tags": [ "public", "alerts" ], "summary": "List alert rules", "description": "List or read public alert-rules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_alert_rules", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert rules", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alertRules": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "detectionId", "detectionName", "enabled", "id", "name", "ruleType", "severity", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "alertRules", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "enabled", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "all", "true", "false" ] }, "description": "enabled query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "ruleType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "description": "ruleType query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "alerts", "configuration" ], "summary": "Create an alert rule", "description": "Create or trigger public alert-rules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_alert_rules", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Alert rule created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "channelMask": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" }, "webhookCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "email", "slack", "webhookCount" ], "additionalProperties": false }, "conditions": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "conditionsTruncated": { "type": "boolean" }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "descriptionTruncated": { "type": "boolean" }, "metricAggregation": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "createdAt", "detectionId", "detectionName", "enabled", "id", "name", "ruleType", "severity", "updatedAt", "channelMask", "conditions", "conditionsTotal", "conditionsTruncated", "conditionsLogicalOp", "cooldownMinutes", "description", "descriptionTruncated", "metricAggregation", "metricDetectionFilter", "metricName", "metricOperator", "metricThresholdValue", "silenceMinutes", "thresholdCount", "windowMinutes" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Alert rule conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channelMask": { "anyOf": [ { "type": "object", "properties": { "email": { "default": false, "type": "boolean" }, "slack": { "default": false, "type": "boolean" }, "webhookIds": { "default": [], "maxItems": 1, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "additionalProperties": false }, { "type": "null" } ] }, "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "default": ">=", "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "metricAggregation": { "anyOf": [ { "type": "string", "enum": [ "sum", "avg", "min", "max", "p95", "p99", "count", "rate" ] }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "enum": [ "cost", "latency", "error_rate", "tokens_total", "tokens_input", "tokens_output", "detection_rate", "trace_count", "tool_failure_rate" ] }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] } }, "required": [ "name", "ruleType" ], "additionalProperties": false, "oneOf": [ { "type": "object", "properties": { "ruleType": { "const": "threshold" } }, "required": [ "ruleType", "detectionId", "thresholdCount", "windowMinutes" ] }, { "type": "object", "properties": { "ruleType": { "const": "per_event" } }, "required": [ "ruleType", "detectionId" ] }, { "type": "object", "properties": { "ruleType": { "const": "compound" } }, "required": [ "ruleType", "conditions" ] }, { "type": "object", "properties": { "ruleType": { "const": "ingestion_health" } }, "required": [ "ruleType", "silenceMinutes" ] }, { "type": "object", "properties": { "metricName": { "enum": [ "cost", "latency", "error_rate", "tokens_total", "tokens_input", "tokens_output", "trace_count", "tool_failure_rate" ] }, "ruleType": { "const": "metric_threshold" } }, "required": [ "ruleType", "metricName", "metricAggregation", "metricOperator", "metricThresholdValue" ] }, { "type": "object", "properties": { "metricName": { "const": "detection_rate" }, "ruleType": { "const": "metric_threshold" } }, "required": [ "ruleType", "metricName", "metricAggregation", "metricOperator", "metricThresholdValue", "metricDetectionFilter" ] } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/alert-rules/{alertRuleId}": { "delete": { "tags": [ "public", "alerts", "configuration" ], "summary": "Delete an alert rule", "description": "Delete public alert-rules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_alert_rules_alertRuleId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert rule deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alertRuleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "alertRuleId", "deleted" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "alerts" ], "summary": "Get an alert rule", "description": "Fetch a specific public alert-rules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_alert_rules_alertRuleId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert rule", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "channelMask": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" }, "webhookCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "email", "slack", "webhookCount" ], "additionalProperties": false }, "conditions": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "conditionsTruncated": { "type": "boolean" }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "descriptionTruncated": { "type": "boolean" }, "metricAggregation": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "createdAt", "detectionId", "detectionName", "enabled", "id", "name", "ruleType", "severity", "updatedAt", "channelMask", "conditions", "conditionsTotal", "conditionsTruncated", "conditionsLogicalOp", "cooldownMinutes", "description", "descriptionTruncated", "metricAggregation", "metricDetectionFilter", "metricName", "metricOperator", "metricThresholdValue", "silenceMinutes", "thresholdCount", "windowMinutes" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "alerts", "configuration" ], "summary": "Update an alert rule", "description": "Partially update public alert-rules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_alert_rules_alertRuleId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert rule updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "channelMask": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" }, "webhookCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "email", "slack", "webhookCount" ], "additionalProperties": false }, "conditions": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "conditionsTruncated": { "type": "boolean" }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "descriptionTruncated": { "type": "boolean" }, "metricAggregation": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "createdAt", "detectionId", "detectionName", "enabled", "id", "name", "ruleType", "severity", "updatedAt", "channelMask", "conditions", "conditionsTotal", "conditionsTruncated", "conditionsLogicalOp", "cooldownMinutes", "description", "descriptionTruncated", "metricAggregation", "metricDetectionFilter", "metricName", "metricOperator", "metricThresholdValue", "silenceMinutes", "thresholdCount", "windowMinutes" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Alert rule conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "channelMask": { "anyOf": [ { "type": "object", "properties": { "email": { "default": false, "type": "boolean" }, "slack": { "default": false, "type": "boolean" }, "webhookIds": { "default": [], "maxItems": 1, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "additionalProperties": false }, { "type": "null" } ] }, "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "default": ">=", "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "metricAggregation": { "anyOf": [ { "type": "string", "enum": [ "sum", "avg", "min", "max", "p95", "p99", "count", "rate" ] }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "enum": [ "cost", "latency", "error_rate", "tokens_total", "tokens_input", "tokens_output", "detection_rate", "trace_count", "tool_failure_rate" ] }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 525600 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/alert-rules/{alertRuleId}/history": { "get": { "tags": [ "public", "alerts" ], "summary": "List alert rule change history", "description": "Fetch a specific alert-rules history.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_alert_rules_alertRuleId_history", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Privacy-safe alert rule change history", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "changedFields": { "maxItems": 18, "type": "array", "items": { "type": "string", "enum": [ "conditions", "conditionsLogicalOp", "cooldownMinutes", "description", "detectionId", "detectionName", "enabled", "metricAggregation", "metricDetectionFilter", "metricName", "metricOperator", "metricThresholdValue", "name", "ruleType", "severity", "silenceMinutes", "thresholdCount", "windowMinutes" ] } }, "changeType": { "type": "string", "enum": [ "created", "deleted", "toggled", "updated" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "redactedChangesCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "redactedChangesTruncated": { "type": "boolean" } }, "required": [ "changedFields", "changeType", "createdAt", "id", "redactedChangesCount", "redactedChangesTruncated" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "events", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/alert-rules/{alertRuleId}/status": { "post": { "tags": [ "public", "alerts", "configuration" ], "summary": "Set alert rule status", "description": "Create or trigger alert-rules status.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_alert_rules_alertRuleId_status", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Alert rule status updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "detectionName": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "ruleType": { "type": "string", "enum": [ "threshold", "per_event", "compound", "ingestion_health", "metric_threshold" ] }, "severity": { "type": "string", "enum": [ "critical", "warning", "info" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "channelMask": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" }, "webhookCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "email", "slack", "webhookCount" ], "additionalProperties": false }, "conditions": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "detection": { "type": "string", "minLength": 1, "maxLength": 100 }, "operator": { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, "threshold": { "type": "number" } }, "required": [ "detection", "threshold" ], "additionalProperties": false } }, { "type": "null" } ] }, "conditionsTotal": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "conditionsTruncated": { "type": "boolean" }, "conditionsLogicalOp": { "type": "string", "enum": [ "AND", "OR" ] }, "cooldownMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "descriptionTruncated": { "type": "boolean" }, "metricAggregation": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "metricDetectionFilter": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "metricName": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "metricOperator": { "anyOf": [ { "type": "string", "enum": [ ">=", ">", "==", "<", "<=" ] }, { "type": "null" } ] }, "metricThresholdValue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "silenceMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "thresholdCount": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "windowMinutes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "createdAt", "detectionId", "detectionName", "enabled", "id", "name", "ruleType", "severity", "updatedAt", "channelMask", "conditions", "conditionsTotal", "conditionsTruncated", "conditionsLogicalOp", "cooldownMinutes", "description", "descriptionTruncated", "metricAggregation", "metricDetectionFilter", "metricName", "metricOperator", "metricThresholdValue", "silenceMinutes", "thresholdCount", "windowMinutes" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/alert-rules/{alertRuleId}/test": { "post": { "tags": [ "public", "alerts", "configuration" ], "summary": "Test or simulate an alert fire", "description": "Create or trigger alert-rules test.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_alert_rules_alertRuleId_test", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Alert test or simulation accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alertRuleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "channels": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "slack", "webhook" ] }, "outcome": { "type": "string", "enum": [ "simulated", "queued" ] } }, "required": [ "channel", "outcome" ], "additionalProperties": false } }, "mode": { "type": "string", "enum": [ "dry_run", "deliver" ] }, "testFireId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "webhookCount": { "type": "integer", "minimum": 0, "maximum": 50 } }, "required": [ "alertRuleId", "channels", "mode", "testFireId", "webhookCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Alert rule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "alertRuleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "alertRuleId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "dry_run", "deliver" ] } }, "required": [ "mode" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/analytics/chart": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics chart", "description": "Create or trigger analytics chart.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_chart", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics chart", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "buckets": { "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "averageDurationMs": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, { "type": "null" } ] }, "detectionGroups": { "type": "object", "properties": { "negative": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "neutral": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "positive": { "type": "number", "minimum": 0, "maximum": 1000000000000000 } }, "required": [ "negative", "neutral", "positive" ], "additionalProperties": false }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "averageDurationMs", "detectionGroups", "start", "totalCostUsd", "traceCount" ], "additionalProperties": false } }, "granularity": { "type": "string", "enum": [ "minute_5", "hour", "day" ] }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "timezone": { "type": "string", "maxLength": 64 } }, "required": [ "buckets", "granularity", "period", "timezone" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "granularity": { "type": "string", "enum": [ "minute_5", "hour", "day" ] }, "timezone": { "default": "UTC", "type": "string" } }, "required": [ "from", "to", "granularity" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/cost": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics cost breakdown", "description": "Create or trigger analytics cost.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_cost", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics cost breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "cost" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "totalTokens": { "type": "number", "minimum": 0, "maximum": 1000000000000000 } }, "required": [ "group", "traceCount", "totalCostUsd", "totalTokens" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/detections": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics detection breakdown", "description": "Create or trigger analytics detections.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_detections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics detection breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "detections" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hitCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "group", "traceCount", "hitCount" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/errors": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics error breakdown", "description": "Create or trigger analytics errors.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_errors", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics error breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "errors" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "group", "traceCount", "errorCount" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/export": { "post": { "tags": [ "public", "analytics", "export" ], "summary": "Export bounded analytics rows", "description": "Create or trigger analytics export.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Complete bounded analytics export", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "dataset": { "type": "string", "const": "traces" }, "endTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "rows": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "spanCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completionTokens", "durationMs", "endedAt", "promptTokens", "sessionId", "spanCount", "startedAt", "status", "totalCostUsd", "totalTokens", "traceId", "workflowName" ], "additionalProperties": false } }, "startTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "dataset", "endTime", "rowCount", "rows", "startTime" ], "additionalProperties": false }, { "type": "object", "properties": { "dataset": { "type": "string", "const": "spans" }, "endTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "rows": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "completionTokens", "costUsd", "durationMs", "endedAt", "framework", "model", "parentSpanId", "promptTokens", "provider", "spanId", "spanName", "spanType", "startedAt", "status", "totalTokens", "traceId" ], "additionalProperties": false } }, "startTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "dataset", "endTime", "rowCount", "rows", "startTime" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Analytics export exceeds complete response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "dataset": { "type": "string", "const": "traces" }, "endTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "startTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "filters": { "type": "object", "properties": { "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "traceIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false } }, "required": [ "dataset", "endTime", "startTime" ], "additionalProperties": false }, { "type": "object", "properties": { "dataset": { "type": "string", "const": "spans" }, "endTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "startTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "filters": { "type": "object", "properties": { "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "traceIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "frameworks": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "models": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "providers": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "spanTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false } }, "required": [ "dataset", "endTime", "startTime" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/facets": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics facets", "description": "Create or trigger analytics facets.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_facets", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics facets", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "facets": { "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "workflowName", "detections", "sessionId", "status" ] }, "hasMore": { "type": "boolean" }, "options": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "count", "label", "value" ], "additionalProperties": false } } }, "required": [ "field", "hasMore", "options" ], "additionalProperties": false } }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "required": [ "facets", "period" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "fields": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "enum": [ "workflowName", "detections", "sessionId", "status" ] } }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "search": { "type": "string", "maxLength": 100 } }, "required": [ "from", "to", "fields" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/kpis": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics KPIs", "description": "Create or trigger analytics kpis.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_kpis", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics KPI summary", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changePercent": { "type": "object", "properties": { "averageDurationMs": { "type": "number", "minimum": -1000000, "maximum": 1000000 }, "averageTokens": { "type": "number", "minimum": -1000000, "maximum": 1000000 }, "detectionHitRate": { "type": "number", "minimum": -1000000, "maximum": 1000000 }, "errorRate": { "type": "number", "minimum": -1000000, "maximum": 1000000 }, "totalCostUsd": { "type": "number", "minimum": -1000000, "maximum": 1000000 }, "traceCount": { "type": "number", "minimum": -1000000, "maximum": 1000000 } }, "required": [ "averageDurationMs", "averageTokens", "detectionHitRate", "errorRate", "totalCostUsd", "traceCount" ], "additionalProperties": false }, "current": { "type": "object", "properties": { "averageDurationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "averageTokens": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "detectionHitRate": { "type": "number", "minimum": 0, "maximum": 1 }, "errorRate": { "type": "number", "minimum": 0, "maximum": 1 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "averageDurationMs", "averageTokens", "detectionHitRate", "errorRate", "totalCostUsd", "traceCount" ], "additionalProperties": false }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "previous": { "type": "object", "properties": { "averageDurationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "averageTokens": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "detectionHitRate": { "type": "number", "minimum": 0, "maximum": 1 }, "errorRate": { "type": "number", "minimum": 0, "maximum": 1 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "averageDurationMs", "averageTokens", "detectionHitRate", "errorRate", "totalCostUsd", "traceCount" ], "additionalProperties": false } }, "required": [ "changePercent", "current", "period", "previous" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/time": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics time breakdown", "description": "Create or trigger analytics time.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_time", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics time breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "time" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "averageDurationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "totalDurationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 } }, "required": [ "group", "traceCount", "averageDurationMs", "totalDurationMs" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/tools": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics tool breakdown", "description": "Create or trigger analytics tools.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_tools", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics tool breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "tools" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "averageDurationMs": { "type": "number", "minimum": 0, "maximum": 1000000000000000 }, "callCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "group", "traceCount", "averageDurationMs", "callCount", "errorCount" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/analytics/waste": { "post": { "tags": [ "public", "analytics" ], "summary": "Query analytics waste breakdown", "description": "Create or trigger analytics waste.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_analytics_waste", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded analytics waste breakdown", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "breakdown": { "type": "string", "const": "waste" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "rows": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hitCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "group", "traceCount", "hitCount" ], "additionalProperties": false } }, "truncation": { "type": "object", "properties": { "limit": { "type": "number", "const": 100 }, "truncated": { "type": "boolean" } }, "required": [ "limit", "truncated" ], "additionalProperties": false } }, "required": [ "breakdown", "period", "rows", "truncation" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filters": { "type": "object", "properties": { "detections": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "sessionIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "statuses": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "OK", "ERROR" ] } }, "workflowNames": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "additionalProperties": false }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/api-keys": { "get": { "tags": [ "public", "access", "api-keys" ], "summary": "List API-key metadata", "description": "List or read public api-keys.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_api_keys", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded redacted API-key metadata page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "apiKeys": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastFour": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-]{4}$" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prefix": { "type": "string", "minLength": 1, "maxLength": 24 }, "rateLimitPerMinute": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "scopeRegistryVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "scopes": { "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "state": { "type": "string", "enum": [ "active", "expired", "inactive" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "expiresAt", "id", "lastFour", "lastUsedAt", "name", "prefix", "rateLimitPerMinute", "scopeRegistryVersion", "scopes", "state", "updatedAt" ], "additionalProperties": false } }, "legacyProjectKey": { "type": "object", "properties": { "configured": { "type": "boolean" }, "kind": { "type": "string", "const": "legacy_project_key" } }, "required": [ "configured", "kind" ], "additionalProperties": false }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "apiKeys", "legacyProjectKey", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "access", "credentials" ], "summary": "Create a Public API key", "description": "Create or trigger public api-keys.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_api_keys", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Credential created; plaintext is returned once and client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_api_keys" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential lifecycle conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "rateLimitPerMinute": { "default": 60, "type": "integer", "minimum": 1, "maximum": 600 }, "scopes": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "project:read", "observability:read" ] }, "uniqueItems": true } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/api-keys/{credentialId}": { "delete": { "tags": [ "public", "access", "credentials" ], "summary": "Revoke a Public API key", "description": "Delete public api-keys.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_api_keys_credentialId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Credential revoked", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "state": { "type": "string", "const": "revoked" } }, "required": [ "id", "revokedAt", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "credentialId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/public/api-keys/{credentialId}/rotate": { "post": { "tags": [ "public", "access", "credentials" ], "summary": "Rotate a Public API key", "description": "Create or trigger api-keys rotate.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_api_keys_credentialId_rotate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Credential created; plaintext is returned once and client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_api_keys_credentialId_rotate" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential lifecycle conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "credentialId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/coding-tools/connections": { "get": { "tags": [ "public", "coding-tools", "configuration" ], "summary": "List coding-tool connections", "description": "List or read coding-tools connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_coding_tools_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted current-user coding-tool connections", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connections": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "authMethod": { "type": "string", "enum": [ "api_key", "azure", "bedrock", "subscription" ] }, "configured": { "type": "boolean", "const": true }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "cursor", "claude_code", "codex" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authMethod", "configured", "connectedAt", "connectionId", "createdAt", "enabled", "provider", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "connections", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "coding-tools", "configuration" ], "summary": "Connect a coding tool", "description": "Create or trigger coding-tools connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_coding_tools_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Coding-tool connection created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authMethod": { "type": "string", "enum": [ "api_key", "azure", "bedrock", "subscription" ] }, "configured": { "type": "boolean", "const": true }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "cursor", "claude_code", "codex" ] }, "kind": { "type": "string", "const": "coding_tool" } }, "required": [ "authMethod", "configured", "connectedAt", "connectionId", "enabled", "provider", "kind" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Coding-tool configuration is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "authMethod": { "type": "string", "const": "api_key" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true } }, "required": [ "apiKey" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "cursor" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "authMethod": { "type": "string", "const": "subscription" }, "credentials": { "type": "object", "properties": { "oauthToken": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true } }, "required": [ "oauthToken" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "claude_code" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "authMethod": { "type": "string", "const": "api_key" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true } }, "required": [ "apiKey" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "claude_code" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "authMethod": { "type": "string", "const": "bedrock" }, "credentials": { "type": "object", "properties": { "awsAccessKeyId": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true }, "awsRegion": { "type": "string", "minLength": 1, "maxLength": 128 }, "awsSecretAccessKey": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true } }, "required": [ "awsAccessKeyId", "awsRegion", "awsSecretAccessKey" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "claude_code" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "authMethod": { "type": "string", "const": "api_key" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true } }, "required": [ "apiKey" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "codex" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "authMethod": { "type": "string", "const": "azure" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 8192, "writeOnly": true }, "apiVersion": { "type": "string", "minLength": 1, "maxLength": 255 }, "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "deploymentName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "apiKey", "apiVersion", "baseUrl", "deploymentName" ], "additionalProperties": false }, "enabled": { "default": true, "type": "boolean" }, "provider": { "type": "string", "const": "codex" } }, "required": [ "authMethod", "credentials", "provider" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/coding-tools/connections/{connectionId}": { "delete": { "tags": [ "public", "coding-tools", "configuration" ], "summary": "Disconnect a coding-tool connection", "description": "Delete coding-tools connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_coding_tools_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Coding-tool connection disconnected", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "disconnected": { "type": "boolean", "const": true } }, "required": [ "connectionId", "disconnected" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "coding-tools", "configuration" ], "summary": "Update a coding-tool connection", "description": "Partially update coding-tools connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_coding_tools_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Coding-tool connection updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authMethod": { "type": "string", "enum": [ "api_key", "azure", "bedrock", "subscription" ] }, "configured": { "type": "boolean", "const": true }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "cursor", "claude_code", "codex" ] }, "kind": { "type": "string", "const": "coding_tool" } }, "required": [ "authMethod", "configured", "connectedAt", "connectionId", "enabled", "provider", "kind" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Coding-tool configuration is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": false, "properties": { "authMethod": { "not": {}, "x-neatlogs-typescript-never": true }, "credentials": { "not": {}, "x-neatlogs-typescript-never": true }, "enabled": { "type": "boolean" }, "provider": { "not": {}, "x-neatlogs-typescript-never": true } }, "required": [ "enabled" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "api_key" }, "credentials": { "additionalProperties": false, "properties": { "apiKey": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "apiKey" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "cursor" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "subscription" }, "credentials": { "additionalProperties": false, "properties": { "oauthToken": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "oauthToken" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "claude_code" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "api_key" }, "credentials": { "additionalProperties": false, "properties": { "apiKey": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "apiKey" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "claude_code" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "bedrock" }, "credentials": { "additionalProperties": false, "properties": { "awsAccessKeyId": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true }, "awsRegion": { "maxLength": 128, "minLength": 1, "type": "string" }, "awsSecretAccessKey": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "awsAccessKeyId", "awsRegion", "awsSecretAccessKey" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "claude_code" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "api_key" }, "credentials": { "additionalProperties": false, "properties": { "apiKey": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "apiKey" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "codex" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" }, { "additionalProperties": false, "properties": { "authMethod": { "const": "azure" }, "credentials": { "additionalProperties": false, "properties": { "apiKey": { "maxLength": 8192, "minLength": 1, "type": "string", "writeOnly": true }, "apiVersion": { "maxLength": 255, "minLength": 1, "type": "string" }, "baseUrl": { "format": "uri", "maxLength": 2048, "type": "string" }, "deploymentName": { "maxLength": 255, "minLength": 1, "type": "string" } }, "required": [ "apiKey", "apiVersion", "baseUrl", "deploymentName" ], "type": "object" }, "enabled": { "type": "boolean" }, "provider": { "const": "codex" } }, "required": [ "provider", "authMethod", "credentials" ], "type": "object" } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/coding-tools/status": { "get": { "tags": [ "public", "coding-tools", "configuration" ], "summary": "Get coding-tool configuration status", "description": "List or read coding-tools status.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_coding_tools_status", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted current-user coding-tool configuration status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "legacyCursorCredentialConfigured": { "type": "boolean" }, "providers": { "minItems": 3, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "configured": { "type": "boolean" }, "hasRecordedRuns": { "type": "boolean" }, "lastConfiguredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "lastRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "cursor", "claude_code", "codex" ] }, "recordedRunCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "configured", "hasRecordedRuns", "lastConfiguredAt", "lastRunAt", "provider", "recordedRunCount" ], "additionalProperties": false } } }, "required": [ "legacyCursorCredentialConfigured", "providers" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/credential-migrations": { "post": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Create a privilege-nonexpanding credential migration", "description": "Create or trigger public credential-migrations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credential_migrations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Credential migration preview created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replacementCredentialId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "replacementKind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "sourceCredentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceKind": { "type": "string", "enum": [ "legacy_project_key", "public_api_key" ] }, "state": { "type": "string", "enum": [ "cancelled", "cutover_pending", "failed", "previewed", "replacement_issued", "source_revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "id", "projectId", "replacementCredentialId", "replacementKind", "sourceCredentialId", "sourceKind", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential migration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "replacement": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "kind": { "type": "string", "const": "public_api_key" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "rateLimitPerMinute": { "type": "integer", "minimum": 1, "maximum": 600 }, "scopes": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "project:read", "observability:read" ] } } }, "required": [ "expiresAt", "kind", "name", "rateLimitPerMinute", "scopes" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "public_api_key" } }, "required": [ "credentialId", "kind" ], "additionalProperties": false } }, "required": [ "replacement", "source" ], "additionalProperties": false }, { "type": "object", "properties": { "replacement": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "kind": { "type": "string", "const": "project_ingest" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "expiresAt", "kind", "name" ], "additionalProperties": false }, "source": { "type": "object", "properties": { "kind": { "type": "string", "const": "legacy_project_key" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "kind", "projectId" ], "additionalProperties": false } }, "required": [ "replacement", "source" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/credential-migrations/{migrationId}": { "get": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Get a credential migration", "description": "Fetch a specific public credential-migrations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_credential_migrations_migrationId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Credential migration state", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replacementCredentialId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "replacementKind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "sourceCredentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceKind": { "type": "string", "enum": [ "legacy_project_key", "public_api_key" ] }, "state": { "type": "string", "enum": [ "cancelled", "cutover_pending", "failed", "previewed", "replacement_issued", "source_revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "id", "projectId", "replacementCredentialId", "replacementKind", "sourceCredentialId", "sourceKind", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "migrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "migrationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/credential-migrations/{migrationId}/cancel": { "post": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Cancel a credential migration", "description": "Create or trigger credential-migrations cancel.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credential_migrations_migrationId_cancel", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Cancel a credential migration", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replacementCredentialId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "replacementKind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "sourceCredentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceKind": { "type": "string", "enum": [ "legacy_project_key", "public_api_key" ] }, "state": { "type": "string", "enum": [ "cancelled", "cutover_pending", "failed", "previewed", "replacement_issued", "source_revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "id", "projectId", "replacementCredentialId", "replacementKind", "sourceCredentialId", "sourceKind", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential migration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "migrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "migrationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/credential-migrations/{migrationId}/cutover": { "post": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Confirm credential migration cutover", "description": "Create or trigger credential-migrations cutover.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credential_migrations_migrationId_cutover", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Confirm credential migration cutover", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replacementCredentialId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "replacementKind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "sourceCredentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceKind": { "type": "string", "enum": [ "legacy_project_key", "public_api_key" ] }, "state": { "type": "string", "enum": [ "cancelled", "cutover_pending", "failed", "previewed", "replacement_issued", "source_revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "id", "projectId", "replacementCredentialId", "replacementKind", "sourceCredentialId", "sourceKind", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential migration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "migrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "migrationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/credential-migrations/{migrationId}/replacement": { "post": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Issue a credential migration replacement", "description": "Create or trigger credential-migrations replacement.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credential_migrations_migrationId_replacement", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Migration replacement issued; plaintext is client wrapped once", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_credential_migrations_migrationId_replacement" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential migration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "migrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "migrationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/credential-migrations/{migrationId}/revoke-source": { "post": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Revoke a migrated source credential", "description": "Create or trigger credential-migrations revoke-source.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credential_migrations_migrationId_revoke_source", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Revoke a migrated source credential", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replacementCredentialId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "replacementKind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "sourceCredentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceKind": { "type": "string", "enum": [ "legacy_project_key", "public_api_key" ] }, "state": { "type": "string", "enum": [ "cancelled", "cutover_pending", "failed", "previewed", "replacement_issued", "source_revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "id", "projectId", "replacementCredentialId", "replacementKind", "sourceCredentialId", "sourceKind", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential migration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "migrationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "migrationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/credential-migrations/legacy-compatibility": { "get": { "tags": [ "public", "access", "credential-migrations" ], "summary": "Get legacy compatibility retirement readiness", "description": "List or read credential-migrations legacy-compatibility.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_credential_migrations_legacy_compatibility", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Privacy-safe legacy compatibility readiness", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blockers": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "customer_outreach_incomplete", "evidence_unhealthy", "product_approval_missing", "replacement_linkage_missing", "security_approval_missing", "zero_success_window_has_success", "zero_success_window_missing", "zero_success_window_unreviewed" ] } }, "evidenceHealthy": { "type": "boolean" }, "lastSuccessAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "outreachComplete": { "type": "boolean" }, "productApprovedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ready": { "type": "boolean" }, "replacementLinked": { "type": "boolean" }, "reviewedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "securityApprovedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "successCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowEndedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "windowStartedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "blockers", "evidenceHealthy", "lastSuccessAt", "outreachComplete", "productApprovedAt", "projectId", "ready", "replacementLinked", "reviewedAt", "securityApprovedAt", "successCount", "windowEndedAt", "windowStartedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/credentials/emergency-revocations": { "post": { "tags": [ "public", "access", "credentials" ], "summary": "Emergency revoke managed credentials atomically", "description": "Create or trigger credentials emergency-revocations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_credentials_emergency_revocations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Managed credentials revoked atomically", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "credentials": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "state": { "type": "string", "const": "revoked" } }, "required": [ "credentialId", "kind", "revokedAt", "state" ], "additionalProperties": false } }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "credentials", "schemaVersion" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential revocation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "credentialId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "enum": [ "project_ingest", "public_api_key" ] } }, "required": [ "confirmation", "credentialId", "kind" ], "additionalProperties": false } } }, "required": [ "requests" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detection-groups": { "get": { "tags": [ "public", "detections" ], "summary": "List detection groups", "description": "List or read public detection-groups.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detection_groups", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded detection group catalog page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "groups", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "detections" ], "summary": "Create a detection group", "description": "Create or trigger public detection-groups.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detection_groups", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Detection group created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection group conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detection-groups/{groupId}": { "delete": { "tags": [ "public", "detections" ], "summary": "Delete a detection group", "description": "Delete public detection-groups.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_detection_groups_groupId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection group deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "groupId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection group not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection group is in use", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "groupId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "detections" ], "summary": "Get a detection group", "description": "Fetch a specific public detection-groups.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detection_groups_groupId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection group metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection group not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "groupId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "detections" ], "summary": "Update a detection group", "description": "Partially update public detection-groups.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_detection_groups_groupId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection group updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection group not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection group conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "groupId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/detection-suggestion-runs": { "post": { "tags": [ "public", "detections", "suggestions" ], "summary": "Create a durable detection suggestion run", "description": "Create or trigger public detection-suggestion-runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detection_suggestion_runs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Detection suggestion run queued", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acceptedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "dismissedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCode": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC_DETECTION_SUGGESTION_CANCELLED", "PUBLIC_DETECTION_SUGGESTION_PROVIDER_ERROR", "PUBLIC_DETECTION_SUGGESTION_TIMEOUT", "PUBLIC_DETECTION_SUGGESTION_UNAVAILABLE" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled" ] }, "suggestionCount": { "type": "integer", "minimum": 0, "maximum": 50 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "acceptedCount", "cancelRequestedAt", "completedAt", "createdAt", "dismissedCount", "errorCode", "id", "startedAt", "status", "suggestionCount", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "A detection suggestion run is already active", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "traceContextLimit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detection-suggestion-runs/{runId}": { "get": { "tags": [ "public", "detections", "suggestions" ], "summary": "Get a detection suggestion run", "description": "Fetch a specific public detection-suggestion-runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detection_suggestion_runs_runId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection suggestion run", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acceptedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "dismissedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCode": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC_DETECTION_SUGGESTION_CANCELLED", "PUBLIC_DETECTION_SUGGESTION_PROVIDER_ERROR", "PUBLIC_DETECTION_SUGGESTION_TIMEOUT", "PUBLIC_DETECTION_SUGGESTION_UNAVAILABLE" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled" ] }, "suggestionCount": { "type": "integer", "minimum": 0, "maximum": 50 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "acceptedCount", "cancelRequestedAt", "completedAt", "createdAt", "dismissedCount", "errorCode", "id", "startedAt", "status", "suggestionCount", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection suggestion run not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "runId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/detection-suggestion-runs/{runId}/cancel": { "post": { "tags": [ "public", "detections", "suggestions" ], "summary": "Cancel a detection suggestion run", "description": "Create or trigger detection-suggestion-runs cancel.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detection_suggestion_runs_runId_cancel", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection suggestion run cancellation requested", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acceptedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cancelRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "dismissedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorCode": { "anyOf": [ { "type": "string", "enum": [ "PUBLIC_DETECTION_SUGGESTION_CANCELLED", "PUBLIC_DETECTION_SUGGESTION_PROVIDER_ERROR", "PUBLIC_DETECTION_SUGGESTION_TIMEOUT", "PUBLIC_DETECTION_SUGGESTION_UNAVAILABLE" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "cancelled" ] }, "suggestionCount": { "type": "integer", "minimum": 0, "maximum": 50 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "acceptedCount", "cancelRequestedAt", "completedAt", "createdAt", "dismissedCount", "errorCode", "id", "startedAt", "status", "suggestionCount", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection suggestion run not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "runId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/detection-suggestions": { "get": { "tags": [ "public", "detections", "suggestions" ], "summary": "List detection suggestions", "description": "List or read public detection-suggestions.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detection_suggestions", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded detection suggestion page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "suggestions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "draft": { "oneOf": [ { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, "type": { "type": "string", "const": "classifier" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "required": [ "case_sensitive", "operator" ], "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "pii" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "detectionId", "draft", "id", "runId", "status", "updatedAt" ], "additionalProperties": false } } }, "required": [ "page", "suggestions" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detection-suggestions/{suggestionId}/accept": { "post": { "tags": [ "public", "detections", "suggestions" ], "summary": "Accept one detection suggestion", "description": "Create or trigger detection-suggestions accept.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detection_suggestions_suggestionId_accept", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection suggestion accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "draft": { "oneOf": [ { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, "type": { "type": "string", "const": "classifier" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "required": [ "case_sensitive", "operator" ], "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "pii" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "detectionId", "draft", "id", "runId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection suggestion not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection suggestion is terminal", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "suggestionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/detection-suggestions/{suggestionId}/dismiss": { "post": { "tags": [ "public", "detections", "suggestions" ], "summary": "Dismiss one detection suggestion", "description": "Create or trigger detection-suggestions dismiss.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detection_suggestions_suggestionId_dismiss", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection suggestion dismissed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "detectionId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "draft": { "oneOf": [ { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, "type": { "type": "string", "const": "classifier" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "required": [ "case_sensitive", "operator" ], "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "pii" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "detectionId", "draft", "id", "runId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection suggestion not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection suggestion is terminal", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "suggestionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections": { "get": { "tags": [ "public", "detections" ], "summary": "List detections", "description": "List or read public detections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded detection catalog page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "detections": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDetectionSummary" } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "detections", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "groupId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "groupId query parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "default": "active", "type": "string", "enum": [ "active", "paused", "disabled", "inactive", "all" ] }, "description": "status query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "detections" ], "summary": "Create a detection", "description": "Create or trigger public detections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Detection created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicDetectionSummary" }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsInput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, "type": { "type": "string", "const": "classifier" } }, "required": [ "displayName", "groupId", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsInput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "displayName", "groupId", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsInput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "displayName", "groupId", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsInput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "pii" } }, "required": [ "displayName", "groupId", "config", "type" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detections/{detectionId}": { "delete": { "tags": [ "public", "detections" ], "summary": "Delete a detection", "description": "Delete public detections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_detections_detectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "detectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "detectionId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection is in use", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "detections" ], "summary": "Get a detection", "description": "Fetch a specific public detections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detections_detectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "classifier" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "classifier_slug": { "type": "string", "minLength": 1 } }, "required": [ "classifier_slug" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "regex" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "input_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "output_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "case_sensitive": { "default": false, "type": "boolean" } }, "required": [ "operator", "case_sensitive" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "conditional" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "pii" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "entities": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "custom_trained" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "custom_detection_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "method": { "type": "string", "enum": [ "setfit", "qlora" ] }, "artifact_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "required": [ "project_id", "custom_detection_id", "version", "method", "temperature" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "code" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "entrypoint": { "type": "string", "const": "detect" }, "input_schema": { "type": "string", "enum": [ "span.v1", "trace.v1" ] }, "language": { "type": "string", "enum": [ "python", "javascript" ] }, "source": { "type": "string", "minLength": 1, "maxLength": 16384 }, "target": { "type": "string", "enum": [ "span", "trace" ] } }, "required": [ "language", "source", "target" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "groupName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1, "maxLength": 100 }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 }, "type": { "type": "string", "const": "trace_rules" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "generatedDescription": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "runOn": { "anyOf": [ { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "span_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "schema_version": { "default": "trace-rules.v1", "type": "string", "const": "trace-rules.v1" }, "combine": { "type": "string", "enum": [ "all", "any" ] }, "rows": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "match" }, "span": { "type": "object", "properties": { "tests": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "op": { "type": "string", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "matches", "not_matches", "contains_pii", "not_contains_pii", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "value": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "field", "op" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false }, "quantifier": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at_least", "at_most", "exactly", "none" ] }, "count": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "null" } ] } }, "required": [ "kind" ], "additionalProperties": false }, "relation": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "preceded_by", "not_preceded_by", "followed_by", "not_followed_by" ] }, "span": { "type": "object", "properties": { "tests": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "op": { "type": "string", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "matches", "not_matches", "contains_pii", "not_contains_pii", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "value": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "field", "op" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false } }, "required": [ "kind", "span" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "span", "quantifier" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "aggregate" }, "function": { "type": "string", "enum": [ "count", "sum", "average", "minimum", "maximum" ] }, "field": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ] }, "where": { "anyOf": [ { "type": "object", "properties": { "tests": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "op": { "type": "string", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "matches", "not_matches", "contains_pii", "not_contains_pii", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "value": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "field", "op" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false }, { "type": "null" } ] }, "compare": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at_least", "at_most", "exactly" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "kind", "value" ], "additionalProperties": false } }, "required": [ "kind", "function", "compare" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "repeat" }, "span": { "type": "object", "properties": { "tests": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 128 }, "op": { "type": "string", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "matches", "not_matches", "contains_pii", "not_contains_pii", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "value": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "field", "op" ], "additionalProperties": false } } }, "required": [ "tests" ], "additionalProperties": false }, "group_by": { "type": "string", "enum": [ "name", "type", "tool.name", "llm.model" ] }, "compare": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "at_least", "at_most", "exactly" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "kind", "value" ], "additionalProperties": false } }, "required": [ "kind", "span", "group_by", "compare" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "trace" }, "field": { "type": "string", "enum": [ "trace.input", "trace.output", "trace.status", "trace.duration_ms" ] }, "op": { "type": "string", "enum": [ "is", "is_not", "in", "not_in", "contains", "not_contains", "matches", "not_matches", "contains_pii", "not_contains_pii", "gt", "gte", "lt", "lte", "exists", "not_exists" ] }, "value": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "kind", "field", "op" ], "additionalProperties": false } ] } } }, "required": [ "schema_version", "combine", "rows" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "createdAt", "displayName", "groupId", "groupName", "id", "isActive", "slug", "threshold", "type", "updatedAt", "batchFields", "description", "generatedDescription", "runOn", "config" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "detections" ], "summary": "Update a detection", "description": "Partially update public detections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_detections_detectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicDetectionSummary" }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Detection conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsInput" }, { "type": "null" } ] }, "runOn": { "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections/{detectionId}/history": { "get": { "tags": [ "public", "detections" ], "summary": "List detection change history", "description": "Fetch a specific detections history.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detections_detectionId_history", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Privacy-safe detection change history", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "actorKind": { "type": "string", "enum": [ "service", "service_account", "unknown", "user" ] }, "changedFields": { "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "batchFields", "config", "description", "displayName", "groupId", "isActive", "runOn", "threshold" ] } }, "changeType": { "type": "string", "enum": [ "created", "deleted", "toggled", "updated" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "actorKind", "changedFields", "changeType", "createdAt", "id" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "events", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections/{detectionId}/hits": { "get": { "tags": [ "public", "detections" ], "summary": "List detection hits", "description": "Fetch a specific detections hits.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detections_detectionId_hits", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded detection hit references", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "detectedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 64 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "detectedAt", "id", "itemIndex", "score", "spanId", "traceId" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "hits", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections/{detectionId}/status": { "patch": { "tags": [ "public", "detections" ], "summary": "Set detection state", "description": "Partially update detections status.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_detections_detectionId_status", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Detection state updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicDetectionSummary" }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "isActive": { "type": "boolean" } }, "required": [ "isActive" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections/{detectionId}/trends": { "get": { "tags": [ "public", "detections" ], "summary": "Get detection trends", "description": "Fetch a specific detections trends.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_detections_detectionId_trends", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded detection trend buckets", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "buckets": { "maxItems": 2200, "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "count", "start" ], "additionalProperties": false } }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week" ] }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "buckets", "from", "granularity", "to" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Detection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "detectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "detectionId path parameter" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "from query parameter" }, { "name": "granularity", "in": "query", "required": false, "schema": { "default": "day", "type": "string", "enum": [ "hour", "day", "week" ] }, "description": "granularity query parameter" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "to query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/detections/generate": { "post": { "tags": [ "public", "detections" ], "summary": "Generate a bounded detection draft", "description": "Create or trigger detections generate.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detections_generate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Strict public detection draft", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "classifier_slug": { "type": "string", "enum": [ "jailbreaking", "nsfw", "hate", "refusals" ] } }, "required": [ "classifier_slug" ], "additionalProperties": false }, "type": { "type": "string", "const": "classifier" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "required": [ "case_sensitive", "operator" ], "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "batchFields": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isActive": { "default": true, "type": "boolean" }, "issueSemantics": { "anyOf": [ { "$ref": "#/components/schemas/PublicDetectionIssueSemanticsOutput" }, { "type": "null" } ] }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "required": [ "frequency" ], "additionalProperties": false }, "threshold": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 }, "config": { "type": "object", "properties": { "entities": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "EMAIL_ADDRESS", "PHONE_NUMBER", "CREDIT_CARD", "IP_ADDRESS", "URL" ] } }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "pii" } }, "required": [ "displayName", "groupId", "isActive", "runOn", "threshold", "config", "type" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Detection generation is unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goal": { "type": "string", "minLength": 1, "maxLength": 2000 }, "traceContextLimit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "goal" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/detections/preview": { "post": { "tags": [ "public", "detections" ], "summary": "Preview a bounded detection", "description": "Create or trigger detections preview.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_detections_preview", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted detection preview", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "samples": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "spanId": { "type": "string", "minLength": 1, "maxLength": 64 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "spanId", "spanName", "spanType", "startedAt", "traceId" ], "additionalProperties": false } }, "totalCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "samples", "totalCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Detection preview is unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 20 }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "config": { "type": "object", "properties": { "case_sensitive": { "default": false, "type": "boolean" }, "input_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] }, "operator": { "default": "OR", "type": "string", "enum": [ "AND", "OR" ] }, "output_pattern": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 32768 }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "regex" } }, "required": [ "from", "to", "config", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 20 }, "runOn": { "default": { "frequency": "trace" }, "type": "object", "properties": { "frequency": { "default": "trace", "type": "string", "enum": [ "trace", "span_type", "span_name" ] }, "span_names": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "type": "null" } ] }, "span_types": { "anyOf": [ { "maxItems": 128, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "type": "null" } ] } }, "additionalProperties": false }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "config": { "type": "object", "properties": { "conditions": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, { "type": "null" } ] }, "logic": { "anyOf": [ { "type": "string", "enum": [ "AND", "OR" ] }, { "type": "null" } ] }, "root": { "anyOf": [ { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 512 }, "operator": { "type": "string", "enum": [ "=", "!=", ">", "<", ">=", "<=", "contains", "not_contains", "in", "not_in", "is_empty", "is_not_empty" ] }, "type": { "type": "string", "const": "rule" }, "value": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "maxItems": 100, "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "required": [ "field", "operator", "type" ], "additionalProperties": false } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false } ] } }, "logic": { "type": "string", "enum": [ "AND", "OR" ] }, "type": { "type": "string", "const": "group" } }, "required": [ "children", "logic", "type" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "type": { "type": "string", "const": "conditional" } }, "required": [ "from", "to", "config", "type" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluation-assignments": { "get": { "tags": [ "public", "evaluations" ], "summary": "List my evaluation review assignments", "description": "List or read public evaluation-assignments.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluation_assignments", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Caller-scoped evaluation review assignments", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assignments": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "unanswered", "draft", "submitted" ] } }, "required": [ "assignmentId", "batchId", "evaluationId", "itemId", "state" ], "additionalProperties": false } } }, "required": [ "assignments" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation item not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "evaluationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId query parameter" }, { "name": "itemId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluation-cohorts": { "get": { "tags": [ "public", "evaluations" ], "summary": "List evaluation cohorts", "description": "List or read public evaluation-cohorts.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluation_cohorts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded project evaluation cohort page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cohorts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluationName": { "type": "string", "minLength": 1, "maxLength": 255 }, "evaluatorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "itemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "completed" ] }, "submittedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "submittedResponseCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "completedAt", "evaluationId", "evaluationName", "evaluatorCount", "id", "isRecurring", "itemCount", "progressPercent", "reviewDeadline", "sentAt", "status", "submittedCount", "submittedResponseCount", "totalExpected" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "cohorts", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluation-schedules": { "get": { "tags": [ "public", "evaluations" ], "summary": "List evaluation schedules", "description": "List or read public evaluation-schedules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluation_schedules", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded recurring evaluation schedule page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "schedules": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "batchCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "cadence": { "type": "string", "minLength": 1, "maxLength": 20 }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "recipientCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "reminderConfig": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "custom" }, "intervalHours": { "type": "integer", "minimum": 1, "maximum": 168 }, "time": { "type": "string", "pattern": "^(?:(?:0?[1-9]|1[0-2]):[0-5]\\d\\s?(?:AM|PM)|(?:[01]?\\d|2[0-3]):[0-5]\\d)$" } }, "required": [ "frequency", "intervalHours", "time" ], "additionalProperties": false }, { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "none", "every-day", "halfway", "one-day-before" ] } }, "required": [ "frequency" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "reviewDuration": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] } }, "required": [ "batchCount", "cadence", "createdAt", "endsAt", "id", "name", "nextRunAt", "recipientCount", "reminderConfig", "reviewDuration", "startsAt", "status" ], "additionalProperties": false } } }, "required": [ "page", "schedules" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored evaluation schedule cannot be represented by the Public API", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "default": "all", "anyOf": [ { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, { "type": "string", "const": "all" } ] }, "description": "status query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluation-schedules/{scheduleId}": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get an evaluation schedule", "description": "Fetch a specific public evaluation-schedules.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluation_schedules_scheduleId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Recurring evaluation schedule metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batchCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "cadence": { "type": "string", "minLength": 1, "maxLength": 20 }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "recipientCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "reminderConfig": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "custom" }, "intervalHours": { "type": "integer", "minimum": 1, "maximum": 168 }, "time": { "type": "string", "pattern": "^(?:(?:0?[1-9]|1[0-2]):[0-5]\\d\\s?(?:AM|PM)|(?:[01]?\\d|2[0-3]):[0-5]\\d)$" } }, "required": [ "frequency", "intervalHours", "time" ], "additionalProperties": false }, { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "none", "every-day", "halfway", "one-day-before" ] } }, "required": [ "frequency" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "reviewDuration": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] } }, "required": [ "batchCount", "cadence", "createdAt", "endsAt", "id", "name", "nextRunAt", "recipientCount", "reminderConfig", "reviewDuration", "startsAt", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation schedule not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored evaluation schedule cannot be represented by the Public API", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "scheduleId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations": { "get": { "tags": [ "public", "evaluations" ], "summary": "List evaluations", "description": "List or read public evaluations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded evaluation catalog page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluations": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 20 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "isRecurring", "name", "status", "traceSource", "type", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "evaluations", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "default": "all", "anyOf": [ { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, { "type": "string", "const": "all" } ] }, "description": "status query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "evaluations" ], "summary": "Create an evaluation draft", "description": "Create or trigger public evaluations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluation created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 20 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "isRecurring", "name", "status", "traceSource", "type", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchSchedule": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] }, { "type": "null" } ] }, "dailyLimit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1000 }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "reviewDuration": { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] }, "samplingRate": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 }, "sendFrequency": { "type": "string", "enum": [ "immediate", "batched", "manual" ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "traceFilter": {}, "traceSource": { "default": "existing", "type": "string", "enum": [ "existing", "future" ] }, "type": { "default": "human", "type": "string", "enum": [ "human", "ai" ] } }, "required": [ "name" ], "additionalProperties": false, "anyOf": [ { "properties": { "traceSource": { "const": "existing" } }, "type": "object" }, { "anyOf": [ { "properties": { "batchSchedule": { "type": "string" } }, "required": [ "batchSchedule" ], "type": "object" }, { "properties": { "endsAt": { "type": "string" } }, "required": [ "endsAt" ], "type": "object" } ], "properties": { "sendFrequency": { "const": "batched" }, "traceFilter": { "type": "object", "properties": { "cost_max": { "type": "number" }, "cost_min": { "type": "number" }, "datasetKeyword": { "type": "string", "minLength": 1, "pattern": "\\S" }, "date_range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } }, "detectionNameContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "detectionNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "endUserIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "endUserIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "latency_max_ms": { "type": "number" }, "latency_min_ms": { "type": "number" }, "runsOnSpanNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "runsOnSpanTypes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "sessionIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "sessionIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_names": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_types": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "spans_max": { "type": "number" }, "spans_min": { "type": "number" }, "status": { "type": "string", "minLength": 1, "pattern": "\\S" }, "tags": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "workflowName": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "additionalProperties": false }, "traceSource": { "const": "future" } }, "required": [ "traceSource" ], "type": "object" } ], "allOf": [ { "anyOf": [ { "properties": { "traceSource": { "const": "existing" } }, "type": "object" }, { "anyOf": [ { "properties": { "batchSchedule": { "type": "string" } }, "required": [ "batchSchedule" ] }, { "properties": { "endsAt": { "format": "date-time", "type": "string" } }, "required": [ "endsAt" ] } ], "properties": { "sendFrequency": { "const": "batched" }, "traceFilter": { "type": "object", "properties": { "cost_max": { "type": "number" }, "cost_min": { "type": "number" }, "datasetKeyword": { "type": "string", "minLength": 1, "pattern": "\\S" }, "date_range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } }, "detectionNameContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "detectionNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "endUserIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "endUserIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "latency_max_ms": { "type": "number" }, "latency_min_ms": { "type": "number" }, "runsOnSpanNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "runsOnSpanTypes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "sessionIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "sessionIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_names": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_types": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "spans_max": { "type": "number" }, "spans_min": { "type": "number" }, "status": { "type": "string", "minLength": 1, "pattern": "\\S" }, "tags": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "workflowName": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "additionalProperties": false }, "traceSource": { "const": "future" } }, "required": [ "traceSource" ], "type": "object" } ] } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluations-stats": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get evaluation statistics", "description": "List or read public evaluations-stats.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_stats", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded evaluation aggregate statistics", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "averageScore": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "completionRate": { "type": "number", "minimum": 0, "maximum": 100 }, "evaluations": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "archived": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "draft": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "active", "archived", "completed", "draft", "total" ], "additionalProperties": false }, "period": { "type": "string", "enum": [ "24h", "7d", "30d", "90d", "all" ] }, "submittedResponses": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "averageScore", "completionRate", "evaluations", "period", "submittedResponses" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "default": "30d", "type": "string", "enum": [ "24h", "7d", "30d", "90d", "all" ] }, "description": "period query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluations/{evaluationId}": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get an evaluation", "description": "Fetch a specific public evaluations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 20 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "batchSchedule": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "dailyLimit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 32768 }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "nextBatchAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "notificationConfig": { "anyOf": [ { "type": "object", "properties": { "channels": { "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "slack", "email" ] } } }, "additionalProperties": false }, { "type": "null" } ] }, "queuedItemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reminderConfig": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "none", "every-day", "halfway", "one-day-before", "custom" ] }, "intervalHours": { "type": "number", "exclusiveMinimum": 0 }, "time": { "type": "string", "maxLength": 32 } }, "required": [ "frequency" ], "additionalProperties": false }, { "type": "null" } ] }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "reviewDuration": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "samplingRate": { "type": "integer", "minimum": 1, "maximum": 100 }, "sendFrequency": { "type": "string", "enum": [ "immediate", "batched", "manual" ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "traceFilter": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "createdAt", "id", "isRecurring", "name", "status", "traceSource", "type", "updatedAt", "batchSchedule", "dailyLimit", "description", "endsAt", "nextBatchAt", "notificationConfig", "queuedItemCount", "reminderConfig", "reviewDeadline", "reviewDuration", "samplingRate", "sendFrequency", "sentAt", "startsAt", "traceFilter" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "evaluations" ], "summary": "Update an owned evaluation", "description": "Partially update public evaluations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_evaluations_evaluationId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 20 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "isRecurring", "name", "status", "traceSource", "type", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchSchedule": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] }, { "type": "null" } ] }, "dailyLimit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1000 }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "reviewDuration": { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] }, "samplingRate": { "type": "integer", "minimum": 1, "maximum": 100 }, "sendFrequency": { "type": "string", "enum": [ "immediate", "batched", "manual" ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "traceFilter": { "anyOf": [ {}, { "type": "null" } ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] } }, "additionalProperties": false, "anyOf": [ { "properties": { "traceSource": { "const": "existing" } }, "type": "object" }, { "properties": { "sendFrequency": { "const": "batched" }, "traceFilter": { "anyOf": [ { "type": "object", "properties": { "cost_max": { "type": "number" }, "cost_min": { "type": "number" }, "datasetKeyword": { "type": "string", "minLength": 1, "pattern": "\\S" }, "date_range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } }, "detectionNameContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "detectionNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "endUserIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "endUserIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "latency_max_ms": { "type": "number" }, "latency_min_ms": { "type": "number" }, "runsOnSpanNames": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "runsOnSpanTypes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "sessionIdContains": { "type": "string", "minLength": 1, "pattern": "\\S" }, "sessionIds": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_names": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "span_types": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "spans_max": { "type": "number" }, "spans_min": { "type": "number" }, "status": { "type": "string", "minLength": 1, "pattern": "\\S" }, "tags": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "workflowName": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "additionalProperties": false }, { "type": "null" } ] }, "traceSource": { "const": "future" } }, "required": [ "traceSource" ], "type": "object" } ], "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches": { "get": { "tags": [ "public", "evaluations", "batches" ], "summary": "List persisted evaluation batches", "description": "Fetch a specific evaluations batches.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation batches", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batches": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "batchNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "displayState": { "type": "string", "enum": [ "pending", "in_progress", "done", "overdue", "cancelled" ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluatorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 50 }, "submittedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "batchNumber", "completedAt", "displayState", "evaluationId", "evaluatorCount", "id", "itemCount", "progressPercent", "reviewDeadline", "sentAt", "status", "submittedCount", "totalExpected" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "batches", "nextCursor" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}": { "get": { "tags": [ "public", "evaluations", "batches" ], "summary": "Get a persisted evaluation batch", "description": "Fetch a specific evaluations batches.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches_batchId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation batch", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batchNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "displayState": { "type": "string", "enum": [ "pending", "in_progress", "done", "overdue", "cancelled" ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluatorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 50 }, "submittedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "batchNumber", "completedAt", "displayState", "evaluationId", "evaluatorCount", "id", "itemCount", "progressPercent", "reviewDeadline", "sentAt", "status", "submittedCount", "totalExpected" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}/close": { "post": { "tags": [ "public", "evaluations", "batches" ], "summary": "Close an evaluation batch", "description": "Create or trigger batches close.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_batches_batchId_close", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation batch closed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alreadyClosed": { "type": "boolean" }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "closedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "done" } }, "required": [ "alreadyClosed", "batchId", "closedAt", "evaluationId", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}/cube": { "get": { "tags": [ "public", "evaluations", "batches" ], "summary": "List persisted evaluation batch aggregate cube cells", "description": "Fetch a specific batches cube.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches_batchId_cube", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation batch aggregate cube", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cells": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completionPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "questionLabel": { "type": "string", "maxLength": 512 }, "questionLabelTruncated": { "type": "boolean" }, "responseCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "answerCount", "completionPercent", "id", "questionLabel", "questionLabelTruncated", "responseCount" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "cells", "nextCursor" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}/report": { "get": { "tags": [ "public", "evaluations", "batches" ], "summary": "Get a persisted evaluation batch report", "description": "Fetch a specific batches report.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches_batchId_report", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Persisted evaluation batch report", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "generatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "markdownTruncated": { "type": "boolean" } }, "required": [ "generatedAt", "markdown", "markdownTruncated" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}/report/export": { "get": { "tags": [ "public", "evaluations", "batches", "export" ], "summary": "Export a complete persisted evaluation batch report", "description": "Fetch a specific report export.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches_batchId_report_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Complete persisted evaluation batch report export", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "export": { "type": "object", "properties": { "format": { "type": "string", "const": "neatlogs.evaluation.batch-report.v1" }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "format", "generatedAt" ], "additionalProperties": false }, "markdown": { "type": "string", "minLength": 1 } }, "required": [ "batchId", "evaluationId", "export", "markdown" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation batch report is not available", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluation batch report export exceeds the public response budget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/{batchId}/summary": { "get": { "tags": [ "public", "evaluations", "batches" ], "summary": "Get a persisted evaluation batch summary", "description": "Fetch a specific batches summary.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_batches_batchId_summary", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation batch summary", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batchNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "displayState": { "type": "string", "enum": [ "pending", "in_progress", "done", "overdue", "cancelled" ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluatorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 50 }, "submittedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "rosterSnapshotComplete": { "type": "boolean" } }, "required": [ "batchNumber", "completedAt", "displayState", "evaluationId", "evaluatorCount", "id", "itemCount", "progressPercent", "reviewDeadline", "sentAt", "status", "submittedCount", "totalExpected", "rosterSnapshotComplete" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation batch not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "batchId path parameter" }, { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/batches/dispatch": { "post": { "tags": [ "public", "evaluations", "batches" ], "summary": "Dispatch a bounded evaluation batch", "description": "Create or trigger batches dispatch.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_batches_dispatch", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluation batch dispatched", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "batch": { "type": "object", "properties": { "batchNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "displayState": { "type": "string", "enum": [ "pending", "in_progress", "done", "overdue", "cancelled" ] }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluatorCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progressPercent": { "type": "integer", "minimum": 0, "maximum": 100 }, "reviewDeadline": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 50 }, "submittedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "batchNumber", "completedAt", "displayState", "evaluationId", "evaluatorCount", "id", "itemCount", "progressPercent", "reviewDeadline", "sentAt", "status", "submittedCount", "totalExpected" ], "additionalProperties": false } }, "required": [ "batch" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation dispatch conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxAssignments": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxItems": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "maxAssignments", "maxItems" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/close": { "post": { "tags": [ "public", "evaluations" ], "summary": "Close an owned evaluation", "description": "Create or trigger evaluations close.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_close", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation closed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "completed" } }, "required": [ "id", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/cohort/items/batch-add": { "post": { "tags": [ "public", "evaluations" ], "summary": "Add exact items to an owned evaluation cohort", "description": "Create or trigger items batch-add.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_cohort_items_batch_add", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation cohort items added", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add", "remove" ] }, "changedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "normalizedInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previousSelectionRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "rejectedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 1000 }, "resultingItemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "selectionRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "action", "changedCount", "normalizedInputHash", "previousSelectionRevision", "rejectedCount", "requestedCount", "resultingItemCount", "selectionRevision" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation cohort state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluation cohort request cannot be processed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "references": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "evaluation_item" } }, "required": [ "itemId", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "trace" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "traceId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "span" }, "spanId": { "type": "string", "minLength": 1, "maxLength": 64 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "spanId", "traceId" ], "additionalProperties": false } ] } } }, "required": [ "previewHash", "references" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/cohort/items/batch-remove": { "post": { "tags": [ "public", "evaluations" ], "summary": "Remove exact items from an owned evaluation cohort", "description": "Create or trigger items batch-remove.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_cohort_items_batch_remove", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation cohort items removed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add", "remove" ] }, "changedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "normalizedInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "previousSelectionRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "rejectedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 1000 }, "resultingItemCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "selectionRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "action", "changedCount", "normalizedInputHash", "previousSelectionRevision", "rejectedCount", "requestedCount", "resultingItemCount", "selectionRevision" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation cohort state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluation cohort request cannot be processed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previewHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "references": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "evaluation_item" } }, "required": [ "itemId", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "trace" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "traceId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "span" }, "spanId": { "type": "string", "minLength": 1, "maxLength": 64 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "spanId", "traceId" ], "additionalProperties": false } ] } } }, "required": [ "previewHash", "references" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/cohort/preview": { "post": { "tags": [ "public", "evaluations" ], "summary": "Preview an owned evaluation cohort mutation", "description": "Create or trigger cohort preview.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_cohort_preview", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation cohort preview", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "acceptedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "action": { "type": "string", "enum": [ "add", "remove" ] }, "normalizedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "normalizedInputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "rejectedCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "rejections": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "already_present", "duplicate_reference", "invalid_target", "not_present" ] }, "referenceIndex": { "type": "integer", "minimum": 0, "maximum": 999 } }, "required": [ "code", "referenceIndex" ], "additionalProperties": false } }, "requestedCount": { "type": "integer", "minimum": 1, "maximum": 1000 }, "selectionRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "truncatedRejectedCount": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "required": [ "acceptedCount", "action", "normalizedCount", "normalizedInputHash", "rejectedCount", "rejections", "requestedCount", "selectionRevision", "truncatedRejectedCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation cohort state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluation cohort request cannot be processed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "add", "remove" ] }, "references": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "evaluation_item" } }, "required": [ "itemId", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "trace" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "traceId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "span" }, "spanId": { "type": "string", "minLength": 1, "maxLength": 64 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "kind", "spanId", "traceId" ], "additionalProperties": false } ] } } }, "required": [ "action", "references" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/export": { "get": { "tags": [ "public", "evaluations", "export" ], "summary": "Export bounded evaluation response metadata", "description": "Fetch a specific evaluations export.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded evaluation response metadata export", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluation": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isRecurring": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "archived" ] }, "traceSource": { "type": "string", "enum": [ "existing", "future" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 20 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "isRecurring", "name", "status", "traceSource", "type", "updatedAt" ], "additionalProperties": false }, "export": { "type": "object", "properties": { "format": { "type": "string", "const": "neatlogs.evaluation.responses.v1" }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "truncated": { "type": "boolean" }, "truncationReason": { "anyOf": [ { "type": "string", "enum": [ "byte_limit", "row_limit" ] }, { "type": "null" } ] } }, "required": [ "format", "from", "limit", "rowCount", "to", "truncated", "truncationReason" ], "additionalProperties": false }, "responses": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "batchId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "evaluationItemId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemType": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 20 }, { "type": "null" } ] }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "batchId", "evaluationItemId", "id", "itemType", "submittedAt" ], "additionalProperties": false } } }, "required": [ "evaluation", "export", "responses" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "from query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 5000, "type": "integer", "minimum": 1, "maximum": 5000 }, "description": "limit query parameter" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "to query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/form": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get an evaluation form", "description": "Fetch a specific evaluations form.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_form", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation form", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "questions": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "enum": [ "short_answer", "paragraph", "multiple_choice", "checkboxes", "dropdown", "file_upload", "linear_scale", "rating", "multiple_choice_grid", "checkbox_grid" ] }, "isRequired": { "type": "boolean" }, "options": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string", "maxLength": 512 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } } ] } }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "questionText": { "type": "string", "minLength": 1, "maxLength": 16384 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "answerType", "isRequired", "options", "placeholder", "questionId", "questionText", "sortOrder" ], "additionalProperties": false } } }, "required": [ "evaluationId", "id", "name", "questions" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation form not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "put": { "tags": [ "public", "evaluations" ], "summary": "Replace an owned draft evaluation form", "description": "Replace/update evaluations form.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "put_api_v1_public_evaluations_evaluationId_form", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation form replaced", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "questions": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "enum": [ "short_answer", "paragraph", "multiple_choice", "checkboxes", "dropdown", "file_upload", "linear_scale", "rating", "multiple_choice_grid", "checkbox_grid" ] }, "isRequired": { "type": "boolean" }, "options": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string", "maxLength": 512 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } } ] } }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "questionText": { "type": "string", "minLength": 1, "maxLength": 16384 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "answerType", "isRequired", "options", "placeholder", "questionId", "questionText", "sortOrder" ], "additionalProperties": false } } }, "required": [ "evaluationId", "id", "name", "questions" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation form conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "questions": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "enum": [ "short_answer", "paragraph", "multiple_choice", "checkboxes", "dropdown", "file_upload", "linear_scale", "rating", "multiple_choice_grid", "checkbox_grid" ] }, "isRequired": { "default": true, "type": "boolean" }, "options": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string", "maxLength": 512 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } } ] } }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "questionText": { "type": "string", "minLength": 1, "maxLength": 16384 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "answerType", "questionText", "sortOrder" ], "additionalProperties": false } } }, "required": [ "name", "questions" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/items": { "get": { "tags": [ "public", "evaluations" ], "summary": "List evaluation items", "description": "Fetch a specific evaluations items.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_items", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded evaluation item page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "addedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "elementIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "elementKey": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "elementPath": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "elementSide": { "anyOf": [ { "type": "string", "enum": [ "input", "output" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemType": { "type": "string", "enum": [ "trace", "span" ] }, "parentTraceId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "dispatched", "superseded" ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "addedAt", "batchId", "elementIndex", "elementKey", "elementPath", "elementSide", "id", "itemId", "itemType", "parentTraceId", "spanId", "status", "traceId" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "items", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/items/{itemId}": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get an evaluation item", "description": "Fetch a specific evaluations items.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_items_itemId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation item metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "addedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "elementIndex": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "elementKey": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "elementPath": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "elementSide": { "anyOf": [ { "type": "string", "enum": [ "input", "output" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemType": { "type": "string", "enum": [ "trace", "span" ] }, "parentTraceId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "dispatched", "superseded" ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "addedAt", "batchId", "elementIndex", "elementKey", "elementPath", "elementSide", "id", "itemId", "itemType", "parentTraceId", "spanId", "status", "traceId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation item not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/items/{itemId}/review": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get assigned evaluation review context", "description": "Fetch a specific items review.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_items_itemId_review", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Assignment-aware evaluation review context", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "existingResponse": { "anyOf": [ { "type": "object", "properties": { "answers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerValue": { "anyOf": [ { "type": "string", "maxLength": 65536 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answerValue", "questionId" ], "additionalProperties": false } }, "responseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "answers", "responseId", "submittedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "form": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "questions": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "enum": [ "short_answer", "paragraph", "multiple_choice", "checkboxes", "dropdown", "file_upload", "linear_scale", "rating", "multiple_choice_grid", "checkbox_grid" ] }, "isRequired": { "type": "boolean" }, "options": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string", "maxLength": 512 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } } ] } }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "questionText": { "type": "string", "minLength": 1, "maxLength": 16384 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "answerType", "isRequired", "options", "placeholder", "questionId", "questionText", "sortOrder" ], "additionalProperties": false } } }, "required": [ "id", "name", "questions" ], "additionalProperties": false }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "unanswered", "draft", "submitted" ] } }, "required": [ "assignmentId", "evaluationId", "existingResponse", "form", "itemId", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation review not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId path parameter" }, { "name": "assignmentId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "assignmentId query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/items/{itemId}/review/draft": { "put": { "tags": [ "public", "evaluations" ], "summary": "Save an assigned evaluation review draft", "description": "Replace/update review draft.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "put_api_v1_public_evaluations_evaluationId_items_itemId_review_draft", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation review draft saved", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "responseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "savedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "state": { "type": "string", "enum": [ "draft", "submitted" ] } }, "required": [ "assignmentId", "evaluationId", "itemId", "responseId", "savedAt", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation review not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation review conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerValue": { "anyOf": [ { "type": "string", "maxLength": 65536 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answerValue", "questionId" ], "additionalProperties": false }, "uniqueItems": true }, "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answers" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/items/{itemId}/review/submissions": { "post": { "tags": [ "public", "evaluations" ], "summary": "Submit an assigned evaluation review", "description": "Create or trigger review submissions.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_items_itemId_review_submissions", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation review submitted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remainingItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "responseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "const": "submitted" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "assignmentId", "evaluationId", "itemId", "remainingItems", "responseId", "state", "submittedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation review not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation review conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerValue": { "anyOf": [ { "type": "string", "maxLength": 65536 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answerValue", "questionId" ], "additionalProperties": false }, "uniqueItems": true }, "assignmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answers" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/launch": { "post": { "tags": [ "public", "evaluations" ], "summary": "Launch an owned evaluation and assign it to yourself", "description": "Create or trigger evaluations launch.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user and explicit x-project-id; current project RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluations_evaluationId_launch", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation launched and assigned to the current user", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alreadyLaunched": { "type": "boolean" }, "assignedItemCount": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "evaluatorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reviewDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "reviewDuration": { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] }, "status": { "type": "string", "const": "active" } }, "required": [ "alreadyLaunched", "assignedItemCount", "evaluationId", "evaluatorId", "reviewDeadline", "reviewDuration", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluation launch conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignMe": { "type": "boolean", "const": true }, "reviewDuration": { "anyOf": [ { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d{1,2}|[1-7]\\d{3}|8[0-6]\\d{2}|87[0-5]\\d|8760)h$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-9]\\d|[12]\\d{2}|3[0-5]\\d|36[0-5])d$" }, { "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|5[0-2])w$" } ] } }, "required": [ "assignMe", "reviewDuration" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/progress": { "get": { "tags": [ "public", "evaluations" ], "summary": "Get evaluation progress", "description": "Fetch a specific evaluations progress.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_progress", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluation progress", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "drafts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pending": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "submitted": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalEvaluators": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalExpected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "drafts", "pending", "progress", "submitted", "totalEvaluators", "totalExpected", "totalItems" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluations/{evaluationId}/responses": { "get": { "tags": [ "public", "evaluations" ], "summary": "List submitted evaluation responses", "description": "Fetch a specific evaluations responses.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluations_evaluationId_responses", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded submitted evaluation response page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "responses": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "minLength": 1, "maxLength": 30 }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "truncated": { "type": "boolean" }, "value": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ] } }, "required": [ "answerType", "questionId", "truncated", "value" ], "additionalProperties": false } }, "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "answers", "evaluationId", "id", "itemId", "submittedAt" ], "additionalProperties": false } } }, "required": [ "page", "responses" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators": { "get": { "tags": [ "public", "evaluators" ], "summary": "List evaluator definitions", "description": "List or read public evaluators.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluators", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator definitions", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluators": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "outputFieldCount": { "type": "integer", "minimum": 0, "maximum": 50 }, "reasoningEnabled": { "type": "boolean" }, "toolGrantCount": { "type": "integer", "minimum": 0, "maximum": 50 }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "description", "id", "isArchived", "maxBudgetUsd", "maxToolCalls", "modelName", "modelProvider", "name", "outputFieldCount", "reasoningEnabled", "toolGrantCount", "type", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "evaluators", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "description": "includeArchived query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "description": "type query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "evaluators" ], "summary": "Create an evaluator definition", "description": "Create or trigger public evaluators.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluator created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "reasoningEnabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "systemPrompt": { "type": "string", "maxLength": 20000 }, "toolGrants": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "configured", "provider", "toolName" ], "additionalProperties": false } } }, "required": [ "createdAt", "description", "id", "isArchived", "maxBudgetUsd", "maxToolCalls", "modelName", "modelProvider", "name", "reasoningEnabled", "type", "updatedAt", "outputSpec", "systemPrompt", "toolGrants" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluator conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "default": 12, "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "outputSpec": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "reasoningEnabled": { "default": true, "type": "boolean" }, "systemPrompt": { "default": "", "type": "string", "maxLength": 20000 }, "toolGrants": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": {} }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false } }, "type": { "default": "llm_judge", "type": "string", "enum": [ "llm_judge", "agent_judge" ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/evaluators/{evaluatorId}": { "get": { "tags": [ "public", "evaluators" ], "summary": "Get an evaluator definition", "description": "Fetch a specific public evaluators.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluators_evaluatorId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator definition", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "reasoningEnabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "systemPrompt": { "type": "string", "maxLength": 20000 }, "toolGrants": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "configured", "provider", "toolName" ], "additionalProperties": false } } }, "required": [ "createdAt", "description", "id", "isArchived", "maxBudgetUsd", "maxToolCalls", "modelName", "modelProvider", "name", "reasoningEnabled", "type", "updatedAt", "outputSpec", "systemPrompt", "toolGrants" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "evaluators" ], "summary": "Update an evaluator definition", "description": "Partially update public evaluators.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_evaluators_evaluatorId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "reasoningEnabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "systemPrompt": { "type": "string", "maxLength": 20000 }, "toolGrants": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "configured", "provider", "toolName" ], "additionalProperties": false } } }, "required": [ "createdAt", "description", "id", "isArchived", "maxBudgetUsd", "maxToolCalls", "modelName", "modelProvider", "name", "reasoningEnabled", "type", "updatedAt", "outputSpec", "systemPrompt", "toolGrants" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluator conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Updated evaluator exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "reasoningEnabled": { "type": "boolean" }, "systemPrompt": { "type": "string", "maxLength": 20000 }, "toolGrants": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": {} }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false } }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "isArchived": { "type": "boolean" } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/duplicate": { "post": { "tags": [ "public", "evaluators" ], "summary": "Duplicate an evaluator definition", "description": "Create or trigger evaluators duplicate.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators_evaluatorId_duplicate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluator duplicated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 50 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "reasoningEnabled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "llm_judge", "agent_judge" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "systemPrompt": { "type": "string", "maxLength": 20000 }, "toolGrants": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "configured", "provider", "toolName" ], "additionalProperties": false } } }, "required": [ "createdAt", "description", "id", "isArchived", "maxBudgetUsd", "maxToolCalls", "modelName", "modelProvider", "name", "reasoningEnabled", "type", "updatedAt", "outputSpec", "systemPrompt", "toolGrants" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluator conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored evaluator exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/playground": { "post": { "tags": [ "public", "evaluators" ], "summary": "Run a bounded stored evaluator playground", "description": "Create or trigger evaluators playground.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators_evaluatorId_playground", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator playground verdict", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "fields": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "value": {} }, "required": [ "key", "value" ], "additionalProperties": false } }, "overall": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "unknown" ] }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 12 } }, "required": [ "error", "fields", "overall", "overallScore", "status", "toolCalls" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator input not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator execution is unavailable or too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attachmentIds": { "default": [], "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "inputText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "traceId": { "default": "", "type": "string", "maxLength": 255 } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/runs": { "get": { "tags": [ "public", "evaluators" ], "summary": "List evaluator run history", "description": "Fetch a specific evaluators runs.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluators_evaluatorId_runs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator runs", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "runs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "evaluationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "failed", "pending", "running", "succeeded" ] }, "verdict": { "type": "object", "properties": { "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "failed", "succeeded", "unknown" ] }, { "type": "null" } ] } }, "required": [ "overallScore", "status" ], "additionalProperties": false } }, "required": [ "completedAt", "createdAt", "durationMs", "evaluationId", "id", "itemId", "status", "verdict" ], "additionalProperties": false } } }, "required": [ "page", "runs" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator run page exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "evaluators" ], "summary": "Start a durable evaluator run", "description": "Create or trigger evaluators runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators_evaluatorId_runs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Evaluator run accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "evaluatorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fields": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "value": {} }, "required": [ "key", "value" ], "additionalProperties": false } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "overall": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "cancelling", "succeeded", "failed", "cancelled" ] }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 8 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "completedAt", "createdAt", "durationMs", "errorCode", "evaluatorId", "fields", "id", "overall", "overallScore", "spanId", "startedAt", "status", "toolCalls", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluator run conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator is not safe for public execution", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spanId": { "type": "string", "maxLength": 64 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" } }, "required": [ "traceId" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/runs/{runId}": { "get": { "tags": [ "public", "evaluators" ], "summary": "Get a durable evaluator run", "description": "Fetch a specific evaluators runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluators_evaluatorId_runs_runId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator run", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "evaluatorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fields": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "value": {} }, "required": [ "key", "value" ], "additionalProperties": false } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "overall": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "cancelling", "succeeded", "failed", "cancelled" ] }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 8 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "completedAt", "createdAt", "durationMs", "errorCode", "evaluatorId", "fields", "id", "overall", "overallScore", "spanId", "startedAt", "status", "toolCalls", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator run not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator run response is too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "runId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/runs/{runId}/cancel": { "post": { "tags": [ "public", "evaluators" ], "summary": "Cancel a durable evaluator run", "description": "Create or trigger runs cancel.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators_evaluatorId_runs_runId_cancel", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator run cancellation requested", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "evaluatorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fields": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "value": {} }, "required": [ "key", "value" ], "additionalProperties": false } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "overall": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "running", "cancelling", "succeeded", "failed", "cancelled" ] }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 8 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "completedAt", "createdAt", "durationMs", "errorCode", "evaluatorId", "fields", "id", "overall", "overallScore", "spanId", "startedAt", "status", "toolCalls", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator run not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Evaluator run conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator run response is too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "runId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/{evaluatorId}/skills": { "get": { "tags": [ "public", "evaluators" ], "summary": "List skills attached to an evaluator", "description": "Fetch a specific evaluators skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_evaluators_evaluatorId_skills", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator skills", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "skills": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 100000 }, "description": { "type": "string", "maxLength": 1024 }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "position": { "type": "integer", "minimum": 0, "maximum": 100 }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "suggestedQuestions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000 }, "answerType": { "type": "string", "maxLength": 40 }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "required": [ "text" ], "additionalProperties": false } }, "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "versionCreatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "whenToUse": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "body", "description", "name", "position", "skillId", "suggestedQuestions", "version", "versionCreatedAt", "whenToUse" ], "additionalProperties": false } } }, "required": [ "skills" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator skill list exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "evaluatorId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "evaluatorId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/evaluators/preview": { "post": { "tags": [ "public", "evaluators" ], "summary": "Preview a bounded evaluator draft", "description": "Create or trigger evaluators preview.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_evaluators_preview", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator preview verdict", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "fields": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "score": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "value": {} }, "required": [ "key", "value" ], "additionalProperties": false } }, "overall": { "anyOf": [ { "type": "string", "maxLength": 20000 }, { "type": "null" } ] }, "overallScore": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "failed", "succeeded", "unknown" ] }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 12 } }, "required": [ "error", "fields", "overall", "overallScore", "status", "toolCalls" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Evaluator input not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Evaluator execution is unavailable or too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "evaluation:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "definition": { "type": "object", "properties": { "maxBudgetUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "maxToolCalls": { "default": 12, "type": "integer", "minimum": 1, "maximum": 12 }, "modelName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "modelProvider": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "outputSpec": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-zA-Z0-9_]+$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "answerType": { "type": "string", "maxLength": 40 }, "scoreType": { "type": "string", "enum": [ "boolean", "numeric", "categorical", "text" ] }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "required": { "type": "boolean" } }, "required": [ "key", "label" ], "additionalProperties": false } }, "reasoningEnabled": { "default": false, "type": "boolean" }, "systemPrompt": { "default": "", "type": "string", "maxLength": 20000 }, "toolGrants": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "config": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": {} }, "provider": { "type": "string", "enum": [ "neatlogs_mcp", "composio", "http_get", "custom_mcp" ] }, "toolName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] } }, "required": [ "provider" ], "additionalProperties": false } }, "type": { "default": "llm_judge", "type": "string", "enum": [ "llm_judge", "agent_judge" ] } }, "required": [ "outputSpec" ], "additionalProperties": false }, "item": { "type": "object", "properties": { "attachmentIds": { "default": [], "maxItems": 5, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "inputText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "traceId": { "default": "", "type": "string", "maxLength": 255 } }, "additionalProperties": false }, "skillVersionIds": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "definition", "item" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/feedback/bulk": { "post": { "tags": [ "public", "feedback" ], "summary": "Mutate feedback in a bounded bulk request", "description": "Create or trigger feedback bulk.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_feedback_bulk", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Feedback bulk mutation completed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "failed": { "type": "integer", "minimum": 0, "maximum": 100 }, "requested": { "type": "integer", "minimum": 1, "maximum": 100 }, "results": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "trace_feedback.create", "trace_feedback.update", "trace_feedback.delete" ] }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "outcome": { "type": "string", "const": "succeeded" }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "const": "trace_feedback" } }, "required": [ "action", "itemKey", "outcome", "resourceId", "resourceType" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "span_feedback.set", "span_feedback.delete" ] }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "outcome": { "type": "string", "const": "succeeded" }, "resourceId": { "type": "string", "minLength": 1, "maxLength": 128 }, "resourceType": { "type": "string", "const": "span_feedback" } }, "required": [ "action", "itemKey", "outcome", "resourceId", "resourceType" ], "additionalProperties": false } ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "trace_feedback.create", "trace_feedback.update", "trace_feedback.delete", "span_feedback.set", "span_feedback.delete" ] }, "code": { "type": "string", "enum": [ "TARGET_UNAVAILABLE", "TARGET_NOT_READY", "CONFLICT" ] }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "outcome": { "type": "string", "const": "failed" } }, "required": [ "action", "code", "itemKey", "outcome" ], "additionalProperties": false } ] } }, "succeeded": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "failed", "requested", "results", "succeeded" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "trace_feedback.create" }, "body": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 50 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 16384 UTF-8 bytes." }, { "type": "null" } ] }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "target": { "type": "object", "properties": { "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "traceId" ], "additionalProperties": false } }, "required": [ "action", "body", "itemKey", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "trace_feedback.update" }, "body": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 50 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 16384 UTF-8 bytes." }, { "type": "null" } ] }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "target": { "type": "object", "properties": { "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "feedbackId", "traceId" ], "additionalProperties": false } }, "required": [ "action", "body", "itemKey", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "trace_feedback.delete" }, "body": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "target": { "type": "object", "properties": { "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "feedbackId", "traceId" ], "additionalProperties": false } }, "required": [ "action", "body", "itemKey", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "span_feedback.set" }, "body": { "type": "object", "properties": { "note": { "anyOf": [ { "type": "string", "description": "At most 2048 UTF-8 bytes." }, { "type": "null" } ] }, "vote": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "vote" ], "additionalProperties": false }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "target": { "type": "object", "properties": { "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "spanId", "traceId" ], "additionalProperties": false } }, "required": [ "action", "body", "itemKey", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "span_feedback.delete" }, "body": { "type": "object", "properties": { "confirmation": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "confirmation" ], "additionalProperties": false }, "itemKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._:-]+$" }, "target": { "type": "object", "properties": { "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "spanId", "traceId" ], "additionalProperties": false } }, "required": [ "action", "body", "itemKey", "target" ], "additionalProperties": false } ] } } }, "required": [ "items" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/guest-links": { "get": { "tags": [ "public", "sharing" ], "summary": "List guest-link metadata", "description": "List or read public guest-links.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_guest_links", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded redacted guest-link metadata page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "guestLinks": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "permission": { "type": "string", "minLength": 1, "maxLength": 100 }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 50 }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "createdAt", "expiresAt", "id", "lastUsedAt", "permission", "resourceId", "resourceType", "state" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "guestLinks", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "sharing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "sharing" ], "summary": "Mint an evaluation guest link", "description": "Create or trigger public guest-links.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_guest_links", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Guest link minted; one-time secret is client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 }, "operationId": { "type": "string", "const": "post_api_v1_public_guest_links" } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version", "operationId" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Guest link mutation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "sharing:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipientEmail": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "evaluationId", "recipientEmail" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "allOf": [ { "pattern": "^[A-Za-z0-9_-]{43}$" }, { "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } ], "writeOnly": true, "description": "Required 32-byte unpadded base64url secret replay key" }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/guest-links/{guestLinkId}": { "delete": { "tags": [ "public", "sharing" ], "summary": "Revoke a guest link", "description": "Delete public guest-links.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_guest_links_guestLinkId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Guest link revoked", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "const": "revoked" } }, "required": [ "id", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "guestLinkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "guestLinkId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "sharing:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "sharing" ], "summary": "Get guest-link metadata", "description": "Fetch a specific public guest-links.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_guest_links_guestLinkId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted guest-link metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "permission": { "type": "string", "minLength": 1, "maxLength": 100 }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 50 }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "createdAt", "expiresAt", "id", "lastUsedAt", "permission", "resourceId", "resourceType", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Guest link not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "guestLinkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "guestLinkId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "sharing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/guest-links/{guestLinkId}/rotate": { "post": { "tags": [ "public", "sharing" ], "summary": "Rotate a guest link", "description": "Create or trigger guest-links rotate.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_guest_links_guestLinkId_rotate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Guest link rotated; replacement one-time secret is client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 }, "operationId": { "type": "string", "const": "post_api_v1_public_guest_links_guestLinkId_rotate" } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version", "operationId" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Guest link rotation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "guestLinkId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "guestLinkId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "allOf": [ { "pattern": "^[A-Za-z0-9_-]{43}$" }, { "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } ], "writeOnly": true, "description": "Required 32-byte unpadded base64url secret replay key" }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "sharing:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/guest-links/bulk/mint": { "post": { "tags": [ "public", "sharing" ], "summary": "Mint guest links atomically", "description": "Create or trigger bulk mint.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_guest_links_bulk_mint", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Guest links minted; one-time secrets are client wrapped together", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 }, "operationId": { "type": "string", "const": "post_api_v1_public_guest_links_bulk_mint" } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version", "operationId" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 60000, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Guest-link mint target not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Guest-link bulk mint conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Guest-link bulk mint request cannot be processed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "sharing:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipientEmail": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "evaluationId", "recipientEmail" ], "additionalProperties": false } } }, "required": [ "requests" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "allOf": [ { "pattern": "^[A-Za-z0-9_-]{43}$" }, { "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } ], "writeOnly": true, "description": "Required 32-byte unpadded base64url secret replay key" }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/guest-links/bulk/revoke": { "post": { "tags": [ "public", "sharing" ], "summary": "Revoke guest links atomically", "description": "Create or trigger bulk revoke.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_guest_links_bulk_revoke", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Guest links revoked atomically", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "guestLinks": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "const": "revoked" } }, "required": [ "id", "state" ], "additionalProperties": false } }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "guestLinks", "schemaVersion" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Guest-link revoke target not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Guest-link bulk revoke conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Guest-link bulk revoke request cannot be processed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "sharing:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "guestLinkId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation", "guestLinkId" ], "additionalProperties": false } } }, "required": [ "requests" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/guest-links/export": { "get": { "tags": [ "public", "sharing", "export" ], "summary": "Export guest-link metadata", "description": "List or read guest-links export.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_guest_links_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded redacted guest-link metadata export", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "guestLinks": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "permission": { "type": "string", "minLength": 1, "maxLength": 100 }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "minLength": 1, "maxLength": 50 }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "createdAt", "expiresAt", "id", "lastUsedAt", "permission", "resourceId", "resourceType", "state" ], "additionalProperties": false } }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "guestLinks", "schemaVersion" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Guest-link export exceeds the public response budget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "sharing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/guest-review/context": { "get": { "tags": [ "public", "guest-review" ], "summary": "Get guest-review context", "description": "List or read guest-review context.\n\n**Auth:** Requires Authorization: NeatLogsGuest with a guest token bound to one evaluation or batch review resource.", "operationId": "get_api_v1_public_guest_review_context", "x-auth-gate": "public-guest-token", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded guest-review context", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "form": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "questions": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerType": { "type": "string", "enum": [ "short_answer", "paragraph", "multiple_choice", "checkboxes", "dropdown", "file_upload", "linear_scale", "rating", "multiple_choice_grid", "checkbox_grid" ] }, "isRequired": { "type": "boolean" }, "options": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string", "maxLength": 512 }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } } ] } }, { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 512 } }, { "type": "null" } ] }, "placeholder": { "anyOf": [ { "type": "string", "maxLength": 2048 }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "questionText": { "type": "string", "minLength": 1, "maxLength": 16384 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "answerType", "isRequired", "options", "placeholder", "questionId", "questionText", "sortOrder" ], "additionalProperties": false } } }, "required": [ "id", "name", "questions" ], "additionalProperties": false }, { "type": "null" } ] }, "items": { "maxItems": 25, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "inputPreview": { "type": "string" }, "inputTruncated": { "type": "boolean" }, "itemType": { "type": "string", "enum": [ "span", "trace" ] }, "outputPreview": { "type": "string" }, "outputTruncated": { "type": "boolean" }, "submitted": { "type": "boolean" } }, "required": [ "id", "inputPreview", "inputTruncated", "itemType", "outputPreview", "outputTruncated", "submitted" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "resource": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "type": "string", "enum": [ "batch", "evaluation" ] } }, "required": [ "id", "type" ], "additionalProperties": false } }, "required": [ "evaluationId", "form", "items", "page", "resource" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Guest-review context cannot fit the public response budget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "GuestTokenAuth": [] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 25 }, "description": "limit query parameter" } ] } }, "/api/v1/public/guest-review/items/{itemId}/response": { "put": { "tags": [ "public", "guest-review" ], "summary": "Submit a guest-review response", "description": "Replace/update items response.\n\n**Auth:** Requires Authorization: NeatLogsGuest with a guest token bound to one evaluation or batch review resource.", "operationId": "put_api_v1_public_guest_review_items_itemId_response", "x-auth-gate": "public-guest-token", "x-auth-source": "global-gate", "responses": { "200": { "description": "Guest review response submitted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "remainingItems": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "responseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "const": "submitted" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "evaluationId", "itemId", "remainingItems", "responseId", "state", "submittedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Guest review submission conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Guest-review response cannot satisfy the public contract", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "itemId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "GuestTokenAuth": [] } ], "requestBody": { "required": true, "description": "Full replacement of the guest-visible answer set", "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "answerValue": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "questionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "answerValue", "questionId" ], "additionalProperties": false } } }, "required": [ "answers" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/connections": { "get": { "tags": [ "public", "imports", "configuration" ], "summary": "List cached import connection metadata", "description": "List or read imports connections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_imports_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import connection metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connections": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "cachedProjectCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "status": { "type": "string", "enum": [ "unverified", "verified" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "cachedProjectCount", "createdAt", "id", "label", "source", "status", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "connections", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored import connection page cannot be represented safely", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Create and verify an import connection", "description": "Create or trigger imports connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Import connection created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cachedProjectCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "status": { "type": "string", "enum": [ "unverified", "verified" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "cachedProjectCount", "createdAt", "id", "label", "source", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import connection conflicts with an existing connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Import provider credentials could not be verified", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Import provider is temporarily unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "description": "Retry-After response header", "required": false, "schema": { "type": "string", "const": "1" } }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "langfuse" }, "credentials": { "type": "object", "properties": { "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "secretKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } }, "required": [ "baseUrl", "publicKey", "secretKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "braintrust" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "enum": [ "https://api.braintrust.dev", "https://api-eu.braintrust.dev" ] } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "langsmith" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "enum": [ "https://api.smith.langchain.com", "https://eu.api.smith.langchain.com", "https://apac.api.smith.langchain.com", "https://aws.api.smith.langchain.com" ] } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "raindrop" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } }, "required": [ "apiKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "phoenix" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "laminar" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "default": "https://api.lmnr.ai", "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "apiKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials", "name" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/imports/connections/{connectionId}": { "delete": { "tags": [ "public", "imports", "configuration" ], "summary": "Delete an unused import connection", "description": "Delete imports connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_imports_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import connection deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "connectionId", "deleted" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import jobs still reference this connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "imports", "configuration" ], "summary": "Get cached import connection metadata", "description": "Fetch a specific imports connections.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_imports_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import connection metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cachedProjectCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "status": { "type": "string", "enum": [ "unverified", "verified" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "cachedProjectCount", "createdAt", "id", "label", "source", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored import connection cannot be represented safely", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "imports", "configuration" ], "summary": "Update and verify an import connection", "description": "Partially update imports connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_imports_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import connection updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cachedProjectCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "status": { "type": "string", "enum": [ "unverified", "verified" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "cachedProjectCount", "createdAt", "id", "label", "source", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import connection conflicts with an existing connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Import provider credentials could not be verified", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Import provider is temporarily unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "description": "Retry-After response header", "required": false, "schema": { "type": "string", "const": "1" } }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "langfuse" }, "credentials": { "type": "object", "properties": { "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "publicKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "secretKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } }, "required": [ "baseUrl", "publicKey", "secretKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "braintrust" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "enum": [ "https://api.braintrust.dev", "https://api-eu.braintrust.dev" ] } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "langsmith" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "enum": [ "https://api.smith.langchain.com", "https://eu.api.smith.langchain.com", "https://apac.api.smith.langchain.com", "https://aws.api.smith.langchain.com" ] } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "raindrop" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true } }, "required": [ "apiKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "phoenix" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "apiKey", "baseUrl" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "laminar" }, "credentials": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true }, "baseUrl": { "default": "https://api.lmnr.ai", "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "apiKey" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "source", "credentials" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/connections/{connectionId}/source-projects": { "get": { "tags": [ "public", "imports", "configuration" ], "summary": "List cached source projects for an import connection", "description": "Fetch a specific connections source-projects.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_imports_connections_connectionId_source_projects", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Cached import source projects", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cachedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "projects": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "cachedAt", "connectionId", "page", "projects" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Cached source projects cannot be represented safely", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/connections/{connectionId}/verify": { "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Verify an import connection", "description": "Create or trigger connections verify.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_connections_connectionId_verify", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import connection verified", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cachedProjectCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "status": { "type": "string", "enum": [ "unverified", "verified" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "cachedProjectCount", "createdAt", "id", "label", "source", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored import credentials could not be verified", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Import provider is temporarily unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "description": "Retry-After response header", "required": false, "schema": { "type": "string", "const": "1" } }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/jobs": { "get": { "tags": [ "public", "imports", "configuration" ], "summary": "List import jobs for the selected project", "description": "List or read imports jobs.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_imports_jobs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import job metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobs": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "authentication", "configuration", "provider", "rate_limit", "unknown" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mode": { "type": "string", "enum": [ "one_time", "recurring" ] }, "progress": { "type": "object", "properties": { "processed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "processed", "total" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "sourceProjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "cancelled", "failed", "paused", "pending", "running", "succeeded", "unknown" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connectionId", "createdAt", "failureCategory", "id", "mode", "progress", "source", "sourceProjectId", "status", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "jobs", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored import job page cannot be represented safely", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Start a bounded import job", "description": "Create or trigger imports jobs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_jobs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Bounded import job created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maxTraces": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reprocessOfJobId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "sourceProjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "const": "pending" }, "windowFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connectionId", "createdAt", "id", "maxTraces", "reprocessOfJobId", "sourceProjectId", "status", "windowFrom", "windowTo" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import connection not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import job state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "sourceProjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxTraces": { "type": "integer", "minimum": 1, "maximum": 10000 }, "windowFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connectionId", "sourceProjectId", "maxTraces", "windowFrom", "windowTo" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/imports/jobs/{jobId}": { "get": { "tags": [ "public", "imports", "configuration" ], "summary": "Get import job metadata", "description": "Fetch a specific imports jobs.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_imports_jobs_jobId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import job metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "failureCategory": { "anyOf": [ { "type": "string", "enum": [ "authentication", "configuration", "provider", "rate_limit", "unknown" ] }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mode": { "type": "string", "enum": [ "one_time", "recurring" ] }, "progress": { "type": "object", "properties": { "processed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "total": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "processed", "total" ], "additionalProperties": false }, "source": { "type": "string", "enum": [ "langfuse", "braintrust", "raindrop", "langsmith", "phoenix", "laminar" ] }, "sourceProjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "cancelled", "failed", "paused", "pending", "running", "succeeded", "unknown" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connectionId", "createdAt", "failureCategory", "id", "mode", "progress", "source", "sourceProjectId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import job not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored import job cannot be represented safely", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "jobId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/jobs/{jobId}/cancel": { "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Cancel an import job", "description": "Create or trigger jobs cancel.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_jobs_jobId_cancel", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import job cancelled", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "cancelled" } }, "required": [ "id", "updatedAt", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import job not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import job state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "jobId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/jobs/{jobId}/pause": { "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Pause an import job", "description": "Create or trigger jobs pause.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_jobs_jobId_pause", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import job paused", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "paused" } }, "required": [ "id", "updatedAt", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import job not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import job state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "jobId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/jobs/{jobId}/reprocess": { "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Create a bounded reprocessing job", "description": "Create or trigger jobs reprocess.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_jobs_jobId_reprocess", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Bounded import reprocessing job created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maxTraces": { "type": "integer", "minimum": 1, "maximum": 10000 }, "reprocessOfJobId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "sourceProjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "const": "pending" }, "windowFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connectionId", "createdAt", "id", "maxTraces", "reprocessOfJobId", "sourceProjectId", "status", "windowFrom", "windowTo" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import job not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import job state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "jobId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxTraces": { "type": "integer", "minimum": 1, "maximum": 10000 }, "windowFrom": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowTo": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "maxTraces", "windowFrom", "windowTo" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/imports/jobs/{jobId}/resume": { "post": { "tags": [ "public", "imports", "configuration" ], "summary": "Resume a manually paused import job", "description": "Create or trigger jobs resume.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_imports_jobs_jobId_resume", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Import job resumed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "pending" } }, "required": [ "id", "updatedAt", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Import job not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Import job state conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "jobId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/ingest-credentials": { "get": { "tags": [ "public", "access", "ingest-credentials" ], "summary": "List ingest-credential metadata", "description": "List or read public ingest-credentials.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_ingest_credentials", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded redacted ingest-credential metadata page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ingestCredentials": { "maxItems": 50, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastFour": { "type": "string", "minLength": 4, "maxLength": 4 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prefix": { "type": "string", "minLength": 1, "maxLength": 24 }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "binding": { "type": "string", "const": "current_user" }, "kind": { "type": "string", "const": "personal_ingest" } }, "required": [ "createdAt", "expiresAt", "id", "lastFour", "lastUsedAt", "name", "prefix", "revokedAt", "state", "updatedAt", "binding", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastFour": { "type": "string", "minLength": 4, "maxLength": 4 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prefix": { "type": "string", "minLength": 1, "maxLength": 24 }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "binding": { "type": "string", "const": "selected_project" }, "kind": { "type": "string", "const": "project_ingest" } }, "required": [ "createdAt", "expiresAt", "id", "lastFour", "lastUsedAt", "name", "prefix", "revokedAt", "state", "updatedAt", "binding", "kind" ], "additionalProperties": false } ] } }, "legacyPersonalWriteKey": { "anyOf": [ { "type": "object", "properties": { "configuredForSelectedOrganization": { "type": "boolean" }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "kind": { "type": "string", "const": "legacy_personal_write_key" } }, "required": [ "configuredForSelectedOrganization", "createdAt", "kind" ], "additionalProperties": false }, { "type": "null" } ] }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "ingestCredentials", "legacyPersonalWriteKey", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "access", "credentials" ], "summary": "Create a project ingest credential", "description": "Create or trigger public ingest-credentials.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_ingest_credentials", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Credential created; plaintext is returned once and client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_ingest_credentials" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential lifecycle conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/ingest-credentials/{credentialId}": { "delete": { "tags": [ "public", "access", "credentials" ], "summary": "Revoke a project ingest credential", "description": "Delete public ingest-credentials.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_ingest_credentials_credentialId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Credential revoked", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "state": { "type": "string", "const": "revoked" } }, "required": [ "id", "revokedAt", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "credentialId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/public/ingest-credentials/{credentialId}/rotate": { "post": { "tags": [ "public", "access", "credentials" ], "summary": "Rotate a project ingest credential", "description": "Create or trigger ingest-credentials rotate.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_ingest_credentials_credentialId_rotate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Credential created; plaintext is returned once and client wrapped", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_ingest_credentials_credentialId_rotate" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "pattern": "^[A-Za-z0-9_-]{22}$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^[A-Za-z0-9_-]+$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Credential lifecycle conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "credentialId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "description": "x-neatlogs-secret-replay-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations": { "get": { "tags": [ "public", "integrations" ], "summary": "List project integration status", "description": "List or read public integrations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted project integration status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "integrations": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "properties": { "connectionMode": { "type": "string", "enum": [ "api_key", "oauth" ] }, "localStatus": { "type": "boolean" } }, "required": [ "connectionMode", "localStatus" ], "additionalProperties": false }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "providerId": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github", "github_pat", "linear_api" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "capabilities", "configured", "connected", "connectedAt", "createdAt", "enabled", "providerId", "updatedAt" ], "additionalProperties": false } } }, "required": [ "integrations" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Integration status is not representable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/integrations/{providerId}": { "delete": { "tags": [ "public", "integrations", "configuration" ], "summary": "Disconnect a personal-token integration", "description": "Delete public integrations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_integrations_providerId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Integration disconnected", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "providerId": { "type": "string", "enum": [ "github_pat", "linear_api" ] } }, "required": [ "deleted", "providerId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Integration not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github_pat", "linear_api" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "enum": [ "github_pat", "linear_api" ] } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "integrations", "configuration" ], "summary": "Update a personal-token integration", "description": "Partially update public integrations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_integrations_providerId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Integration credentials updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "connected": { "type": "boolean", "const": true }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "providerId": { "type": "string", "enum": [ "github_pat", "linear_api" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "configured", "connected", "connectedAt", "providerId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Integration not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Integration conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Integration credentials are invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github_pat", "linear_api" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "providerId": { "type": "string", "const": "github_pat" }, "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[\\x21-\\x7e]+$", "writeOnly": true } }, "required": [ "providerId", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "providerId": { "type": "string", "const": "linear_api" }, "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[\\x21-\\x7e]+$", "writeOnly": true } }, "required": [ "providerId", "token" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "integrations", "configuration" ], "summary": "Connect a personal-token integration", "description": "Create or trigger public integrations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_integrations_providerId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Integration connected", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "connected": { "type": "boolean", "const": true }, "connectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "providerId": { "type": "string", "enum": [ "github_pat", "linear_api" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "configured", "connected", "connectedAt", "providerId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Integration is already connected", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Integration credentials are invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "github_pat", "linear_api" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "providerId": { "type": "string", "const": "github_pat" }, "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[\\x21-\\x7e]+$", "writeOnly": true } }, "required": [ "providerId", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "providerId": { "type": "string", "const": "linear_api" }, "token": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[\\x21-\\x7e]+$", "writeOnly": true } }, "required": [ "providerId", "token" ], "additionalProperties": false } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/issue-runs": { "post": { "tags": [ "public", "integrations", "issues" ], "summary": "Create a durable Linear or Jira issue run", "description": "Create or trigger integrations issue-runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_integrations_providerId_issue_runs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Durable issue creation run accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "completedAt": { "type": "null" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "type": "null" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "null" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "pending" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "null" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "running" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "issue": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "identifier": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "id", "identifier", "title", "url" ], "additionalProperties": false }, "status": { "type": "string", "const": "succeeded" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "issue", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 96 }, "outboundStartedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "failed" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 96 }, "outboundStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "delivery_unknown" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Integration not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Issue run conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "linear", "jira" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigneeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "body": { "type": "string", "minLength": 1, "maxLength": 65536 }, "issueType": { "type": "string", "minLength": 1, "maxLength": 100 }, "labelIds": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "priority": { "default": "none", "type": "string", "enum": [ "none", "urgent", "high", "medium", "low" ] }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "body", "targetId", "title" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/issue-runs/{runId}": { "get": { "tags": [ "public", "integrations", "issues" ], "summary": "Get a durable issue creation run", "description": "Fetch a specific integrations issue-runs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providerId_issue_runs_runId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Issue creation run", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "completedAt": { "type": "null" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "type": "null" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "null" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "pending" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "null" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "running" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "null" }, "outboundStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "issue": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "identifier": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "id", "identifier", "title", "url" ], "additionalProperties": false }, "status": { "type": "string", "const": "succeeded" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "issue", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 96 }, "outboundStartedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "failed" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false }, { "type": "object", "properties": { "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "type": "string", "minLength": 1, "maxLength": 96 }, "outboundStartedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "provider": { "type": "string", "enum": [ "linear", "jira" ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "const": "delivery_unknown" } }, "required": [ "completedAt", "createdAt", "errorCode", "outboundStartedAt", "provider", "runId", "startedAt", "targetId", "updatedAt", "status" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Issue run not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "linear", "jira" ] }, "description": "providerId path parameter" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "runId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/issue-targets": { "get": { "tags": [ "public", "integrations", "issues" ], "summary": "List bounded Linear or Jira issue targets", "description": "Fetch a specific integrations issue-targets.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providerId_issue_targets", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded issue targets", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "targets": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "key", "name" ], "additionalProperties": false } } }, "required": [ "page", "targets" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "linear", "jira" ] }, "description": "providerId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/issue-targets/{targetId}/labels": { "get": { "tags": [ "public", "integrations", "issues" ], "summary": "List bounded issue labels", "description": "Fetch a specific issue-targets labels.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providerId_issue_targets_targetId_labels", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded issue labels", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "labels": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "labels", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "linear", "jira" ] }, "description": "providerId path parameter" }, { "name": "targetId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "targetId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/issue-targets/{targetId}/members": { "get": { "tags": [ "public", "integrations", "issues" ], "summary": "List bounded issue members", "description": "Fetch a specific issue-targets members.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providerId_issue_targets_targetId_members", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded issue members", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "members": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 320, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "email", "id", "name" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "members", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "linear", "jira" ] }, "description": "providerId path parameter" }, { "name": "targetId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "targetId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/oauth-handoffs": { "post": { "tags": [ "public", "integrations", "oauth" ], "summary": "Start a durable integration OAuth handoff", "description": "Create or trigger integrations oauth-handoffs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_integrations_providerId_oauth_handoffs", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Durable integration OAuth handoff", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorizationUrl": { "type": "string", "maxLength": 4096, "format": "uri", "pattern": "^https:\\/\\/.*" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "handoffId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerId": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github" ] }, "status": { "type": "string", "const": "pending" } }, "required": [ "authorizationUrl", "expiresAt", "handoffId", "providerId", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "OAuth handoff conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "OAuth provider is unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/oauth-handoffs/{handoffId}": { "get": { "tags": [ "public", "integrations", "oauth" ], "summary": "Get a durable integration OAuth handoff", "description": "Fetch a specific integrations oauth-handoffs.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providerId_oauth_handoffs_handoffId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Integration OAuth handoff status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "completionOutcome": { "anyOf": [ { "type": "string", "enum": [ "connected", "access_denied", "authorization_revoked", "invalid_callback", "not_configured", "token_exchange_failed", "provider_error", "workspace_conflict", "expired" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "handoffId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "providerId": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github" ] }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "denied", "expired" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "completedAt", "completionOutcome", "createdAt", "expiresAt", "handoffId", "providerId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "OAuth handoff not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github" ] }, "description": "providerId path parameter" }, { "name": "handoffId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "handoffId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/{providerId}/test": { "post": { "tags": [ "public", "integrations" ], "summary": "Test a reviewed integration provider connection", "description": "Create or trigger integrations test.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_integrations_providerId_test", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Integration provider connection test", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connected": { "type": "boolean", "const": true }, "providerId": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github", "github_pat", "linear_api" ] }, "testedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "connected", "providerId", "testedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Integration not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Integration provider rejected the connection", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github", "github_pat", "linear_api" ] }, "description": "providerId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted" } }, "/api/v1/public/integrations/providers": { "get": { "tags": [ "public", "integrations" ], "summary": "List integration provider capabilities", "description": "List or read integrations providers.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_integrations_providers", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Reviewed integration provider capabilities", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "providers": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "capabilities": { "type": "object", "properties": { "connectionMode": { "type": "string", "enum": [ "api_key", "oauth" ] }, "localStatus": { "type": "boolean" } }, "required": [ "connectionMode", "localStatus" ], "additionalProperties": false }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "id": { "type": "string", "enum": [ "slack", "linear", "jira", "notion", "asana", "basecamp", "github", "github_pat", "linear_api" ] } }, "required": [ "capabilities", "displayName", "id" ], "additionalProperties": false } } }, "required": [ "providers" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Integration status is not representable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/invitations/accept": { "post": { "tags": [ "public", "organizations", "invitations" ], "summary": "Accept an organization invitation", "description": "Create or trigger invitations accept.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_invitations_accept", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Accept an organization invitation", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "membership": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "status": { "type": "string", "const": "active" } }, "required": [ "id", "joinedAt", "role", "status" ], "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "membership", "organizationId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "organization:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 255, "writeOnly": true } }, "required": [ "token" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ] } }, "/api/v1/public/mcp/connections": { "get": { "tags": [ "public", "mcp", "configuration" ], "summary": "List MCP connections", "description": "List or read mcp connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_mcp_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted current-user MCP connections", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connections": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "configuredHeaderNames": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "enabled": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "connected", "failed", "untested" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "configuredHeaderNames", "connectionId", "createdAt", "enabled", "name", "status", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "connections", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "mcp", "configuration" ], "summary": "Connect an MCP server", "description": "Create or trigger mcp connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_mcp_connections", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "MCP connection created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configuredHeaderNames": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "connected", "failed", "untested" ] }, "kind": { "type": "string", "const": "custom_mcp" } }, "required": [ "configuredHeaderNames", "connectionId", "enabled", "name", "status", "kind" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored MCP connection is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "default": true }, "headers": { "additionalProperties": { "maxLength": 8192, "minLength": 1, "pattern": "^[^\\r\\n\\u0000]+$", "type": "string", "writeOnly": true }, "maxProperties": 32, "propertyNames": { "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$", "type": "string" }, "type": "object", "default": {} }, "name": { "maxLength": 128, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/[^\\s/?#@]+(?:\\/[^\\s?#]*)?$", "type": "string" } }, "required": [ "name", "url" ], "type": "object" } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/mcp/connections/{connectionId}": { "delete": { "tags": [ "public", "mcp", "configuration" ], "summary": "Disconnect an MCP connection", "description": "Delete mcp connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_mcp_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "MCP connection disconnected", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "disconnected": { "type": "boolean", "const": true } }, "required": [ "connectionId", "disconnected" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "mcp", "configuration" ], "summary": "Update an MCP connection", "description": "Partially update mcp connections.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_mcp_connections_connectionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "MCP connection updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configuredHeaderNames": { "maxItems": 32, "type": "array", "items": { "type": "string", "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$" } }, "connectionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "enabled": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "status": { "type": "string", "enum": [ "connected", "failed", "untested" ] }, "kind": { "type": "string", "const": "custom_mcp" } }, "required": [ "configuredHeaderNames", "connectionId", "enabled", "name", "status", "kind" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored MCP connection is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "connectionId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "headers": { "additionalProperties": { "maxLength": 8192, "minLength": 1, "pattern": "^[^\\r\\n\\u0000]+$", "type": "string", "writeOnly": true }, "maxProperties": 32, "propertyNames": { "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$", "type": "string" }, "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/[^\\s/?#@]+(?:\\/[^\\s?#]*)?$", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "headers": { "additionalProperties": { "maxLength": 8192, "minLength": 1, "pattern": "^[^\\r\\n\\u0000]+$", "type": "string", "writeOnly": true }, "maxProperties": 32, "propertyNames": { "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$", "type": "string" }, "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/[^\\s/?#@]+(?:\\/[^\\s?#]*)?$", "type": "string" } }, "required": [ "headers" ], "type": "object" }, { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "headers": { "additionalProperties": { "maxLength": 8192, "minLength": 1, "pattern": "^[^\\r\\n\\u0000]+$", "type": "string", "writeOnly": true }, "maxProperties": 32, "propertyNames": { "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$", "type": "string" }, "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/[^\\s/?#@]+(?:\\/[^\\s?#]*)?$", "type": "string" } }, "required": [ "name" ], "type": "object" }, { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "headers": { "additionalProperties": { "maxLength": 8192, "minLength": 1, "pattern": "^[^\\r\\n\\u0000]+$", "type": "string", "writeOnly": true }, "maxProperties": 32, "propertyNames": { "pattern": "^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$", "type": "string" }, "type": "object" }, "name": { "maxLength": 128, "minLength": 1, "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "pattern": "^https:\\/\\/[^\\s/?#@]+(?:\\/[^\\s?#]*)?$", "type": "string" } }, "required": [ "url" ], "type": "object" } ] } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/mcp/status": { "get": { "tags": [ "public", "mcp", "configuration" ], "summary": "Get MCP configuration status", "description": "List or read mcp status.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_mcp_status", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted current-user MCP configuration status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "composio": { "type": "object", "properties": { "configured": { "type": "boolean" }, "configuredToolkitCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "configured", "configuredToolkitCount" ], "additionalProperties": false }, "custom": { "type": "object", "properties": { "configured": { "type": "boolean" }, "configuredCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connectedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabledCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "untestedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "configured", "configuredCount", "connectedCount", "enabledCount", "failedCount", "lastCheckedAt", "untestedCount" ], "additionalProperties": false } }, "required": [ "composio", "custom" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/notification-preferences": { "get": { "tags": [ "public", "notifications" ], "summary": "Get current notification preferences", "description": "List or read public notification-preferences.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_notification_preferences", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Current notification preferences", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "approvalRequests": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "commentsMentions": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "configured": { "type": "boolean" }, "criticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "dailyDigest": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "digestTime": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "digestTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "evalAssignments": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "evalUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "experimentUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "nonCriticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "promptChanges": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "quietHoursEnd": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursStart": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "slackDmEnabled": { "type": "boolean" } }, "required": [ "approvalRequests", "commentsMentions", "configured", "criticalAlerts", "dailyDigest", "digestTime", "digestTimezone", "evalAssignments", "evalUpdates", "experimentUpdates", "nonCriticalAlerts", "promptChanges", "quietHoursEnd", "quietHoursStart", "quietHoursTimezone", "slackDmEnabled" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "profile:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] }, "patch": { "tags": [ "public", "notifications" ], "summary": "Update current notification preferences", "description": "Partially update public notification-preferences.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_notification_preferences", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Current notification preferences after update", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "approvalRequests": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "commentsMentions": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "configured": { "type": "boolean" }, "criticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "dailyDigest": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "digestTime": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "digestTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "evalAssignments": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "evalUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "experimentUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "nonCriticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "promptChanges": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "quietHoursEnd": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursStart": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "slackDmEnabled": { "type": "boolean" } }, "required": [ "approvalRequests", "commentsMentions", "configured", "criticalAlerts", "dailyDigest", "digestTime", "digestTimezone", "evalAssignments", "evalUpdates", "experimentUpdates", "nonCriticalAlerts", "promptChanges", "quietHoursEnd", "quietHoursStart", "quietHoursTimezone", "slackDmEnabled" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "profile:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "approvalRequests": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "commentsMentions": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "criticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "dailyDigest": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "digestTime": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "digestTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "evalAssignments": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "evalUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "experimentUpdates": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "nonCriticalAlerts": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "promptChanges": { "type": "object", "properties": { "email": { "type": "boolean" }, "slack": { "type": "boolean" } }, "required": [ "email", "slack" ], "additionalProperties": false }, "quietHoursEnd": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursStart": { "anyOf": [ { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, { "type": "null" } ] }, "quietHoursTimezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "slackDmEnabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/organizations": { "get": { "tags": [ "public", "organizations" ], "summary": "List organizations", "description": "List or read public organizations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded organization page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "organizations": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 255 }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "name", "role", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "organizations", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "context:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ] } }, "/api/v1/public/organizations/{organizationId}": { "get": { "tags": [ "public", "organizations" ], "summary": "Get an organization", "description": "Fetch a specific public organizations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Organization metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "maxLength": 255 }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "name", "role", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" } ], "security": [ { "OAuth2": [ "organization:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/audit/events": { "get": { "tags": [ "public", "audit", "access" ], "summary": "List credential lifecycle audit events", "description": "Fetch a specific audit events.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_audit_events", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded credential lifecycle audit page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "oauth.authorization_granted", "oauth.device_approved", "oauth.device_denied", "oauth.refresh_reuse_detected", "oauth.token_issued", "oauth.token_refreshed", "oauth.token_revoked", "public_api_key.created", "public_api_key.revoked", "public_api_key.rotated", "ingest_credential.created", "ingest_credential.revoked", "ingest_credential.rotated", "service_account.binding_created", "service_account.binding_deleted", "service_account.binding_role_updated", "service_account.created", "service_account.disabled", "service_account.token_minted", "service_account.token_revoked", "service_account.token_rotated", "service_account.updated" ] }, "actorType": { "type": "string", "enum": [ "legacy_public_api_key", "oauth_user", "service", "service_account", "superuser", "unknown", "user" ] }, "createdAt": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "metadata": { "type": "object", "properties": { "bindingCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "expiresAt": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "predecessorTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopeCount": { "type": "integer", "minimum": 0, "maximum": 64 }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "enum": [ "oauth_access_token", "oauth_authorization", "oauth_device_authorization", "oauth_refresh_token_family", "public_api_key", "project_ingest", "service_account", "service_account_project_binding", "service_account_token" ] } }, "required": [ "action", "actorType", "createdAt", "id", "metadata", "organizationId", "projectId", "resourceId", "resourceType" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "events", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/audit/events/export": { "get": { "tags": [ "public", "audit", "access" ], "summary": "Export credential lifecycle audit events", "description": "Fetch a specific events export.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_audit_events_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded credential lifecycle audit export", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "maxItems": 5000, "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "oauth.authorization_granted", "oauth.device_approved", "oauth.device_denied", "oauth.refresh_reuse_detected", "oauth.token_issued", "oauth.token_refreshed", "oauth.token_revoked", "public_api_key.created", "public_api_key.revoked", "public_api_key.rotated", "ingest_credential.created", "ingest_credential.revoked", "ingest_credential.rotated", "service_account.binding_created", "service_account.binding_deleted", "service_account.binding_role_updated", "service_account.created", "service_account.disabled", "service_account.token_minted", "service_account.token_revoked", "service_account.token_rotated", "service_account.updated" ] }, "actorType": { "type": "string", "enum": [ "legacy_public_api_key", "oauth_user", "service", "service_account", "superuser", "unknown", "user" ] }, "createdAt": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "metadata": { "type": "object", "properties": { "bindingCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "expiresAt": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "predecessorTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopeCount": { "type": "integer", "minimum": 0, "maximum": 64 }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "enum": [ "oauth_access_token", "oauth_authorization", "oauth_device_authorization", "oauth_refresh_token_family", "public_api_key", "project_ingest", "service_account", "service_account_project_binding", "service_account_token" ] } }, "required": [ "action", "actorType", "createdAt", "id", "metadata", "organizationId", "projectId", "resourceId", "resourceType" ], "additionalProperties": false } }, "export": { "type": "object", "properties": { "format": { "type": "string", "const": "neatlogs.audit.lifecycle.v1" }, "from": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 5000 }, "to": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "truncated": { "type": "boolean" } }, "required": [ "format", "from", "limit", "rowCount", "to", "truncated" ], "additionalProperties": false } }, "required": [ "events", "export" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "from query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 5000, "type": "integer", "minimum": 1, "maximum": 5000 }, "description": "limit query parameter" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 64, "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "to query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/billing/plans": { "get": { "tags": [ "public", "organizations", "billing" ], "summary": "List organization billing plans", "description": "Fetch a specific billing plans.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_billing_plans", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "List organization billing plans", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plans": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "features": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "isPopular": { "type": "boolean" }, "limits": { "type": "object", "properties": { "events": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "projects": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "teams": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "apiCallsPerMinute": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "storageMb": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "events", "projects", "teams", "apiCallsPerMinute", "storageMb" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "pricing": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 10 }, "monthly": { "type": "number", "minimum": 0 }, "yearly": { "type": "number", "minimum": 0 } }, "required": [ "currency", "monthly", "yearly" ], "additionalProperties": false }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "description", "features", "isPopular", "limits", "name", "pricing", "type" ], "additionalProperties": false } } }, "required": [ "plans" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" } ], "security": [ { "OAuth2": [ "billing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/billing/subscription": { "get": { "tags": [ "public", "organizations", "billing" ], "summary": "Get organization billing subscription", "description": "Fetch a specific billing subscription.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_billing_subscription", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Get organization billing subscription", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "billingCycle": { "type": "object", "properties": { "end": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "start": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "end", "start" ], "additionalProperties": false }, "isActive": { "type": "boolean" }, "limits": { "type": "object", "properties": { "events": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "projects": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "teams": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "events", "projects", "teams" ], "additionalProperties": false }, "plan": { "type": "object", "properties": { "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "displayName", "type" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "active", "cancelled", "past_due", "trial" ] }, "trialEndsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "billingCycle", "isActive", "limits", "plan", "status", "trialEndsAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" } ], "security": [ { "OAuth2": [ "billing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/billing/usage": { "get": { "tags": [ "public", "organizations", "billing" ], "summary": "Get organization billing usage", "description": "Fetch a specific billing usage.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_billing_usage", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Get organization billing usage", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "billingCycleEnd": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "plan": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "cancelled", "past_due", "trial" ] }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "status", "type" ], "additionalProperties": false }, "resources": { "type": "object", "properties": { "events": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "current": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "percentage": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "remaining": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "allowed", "current", "limit", "percentage", "remaining" ], "additionalProperties": false }, "projects": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "current": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "percentage": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "remaining": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "allowed", "current", "limit", "percentage", "remaining" ], "additionalProperties": false }, "teams": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "current": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "percentage": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "remaining": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "allowed", "current", "limit", "percentage", "remaining" ], "additionalProperties": false } }, "required": [ "events", "projects", "teams" ], "additionalProperties": false }, "trialEndsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "billingCycleEnd", "plan", "resources", "trialEndsAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" } ], "security": [ { "OAuth2": [ "billing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/billing/usage-alerts": { "get": { "tags": [ "public", "organizations", "billing" ], "summary": "List organization billing usage alerts", "description": "Fetch a specific billing usage-alerts.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_billing_usage_alerts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "List organization billing usage alerts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "alerts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "acknowledged": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "currentUsage": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "isRead": { "type": "boolean" }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "resource": { "type": "string", "enum": [ "events", "projects", "storage", "teams" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "threshold": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "approaching_limit", "limit_exceeded", "trial_expiring" ] } }, "required": [ "acknowledged", "createdAt", "currentUsage", "id", "isRead", "limit", "message", "resource", "severity", "threshold", "type" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "snapshotAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "alerts", "page", "snapshotAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "state", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "all", "unread", "unacknowledged", "unread-and-unacknowledged" ] }, "description": "state query parameter" } ], "security": [ { "OAuth2": [ "billing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/invitations": { "get": { "tags": [ "public", "organizations", "invitations" ], "summary": "List organization invitations", "description": "Fetch a specific organizations invitations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_invitations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "List organization invitations", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "invitations": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] }, "state": { "type": "string", "enum": [ "pending", "expired" ] } }, "required": [ "createdAt", "email", "expiresAt", "id", "role", "state" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "invitations", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "state", "in": "query", "required": false, "schema": { "default": "pending", "type": "string", "enum": [ "all", "pending", "expired" ] }, "description": "state query parameter" } ], "security": [ { "OAuth2": [ "organization:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "organizations", "invitations" ], "summary": "Invite an organization member", "description": "Create or trigger organizations invitations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_organizations_organizationId_invitations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Invite an organization member", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] }, "state": { "type": "string", "enum": [ "pending", "expired" ] } }, "required": [ "createdAt", "email", "expiresAt", "id", "role", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "organization:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] } }, "required": [ "email", "role" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/invitations/{invitationId}": { "delete": { "tags": [ "public", "organizations", "invitations" ], "summary": "Revoke an organization invitation", "description": "Delete organizations invitations.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_organizations_organizationId_invitations_invitationId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Revoke an organization invitation", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revoked": { "type": "boolean", "const": true } }, "required": [ "email", "id", "revoked" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "invitationId path parameter" }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "organization:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "invitationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "email", "invitationId" ], "additionalProperties": false } } } } } }, "/api/v1/public/organizations/{organizationId}/invitations/{invitationId}/resend": { "post": { "tags": [ "public", "organizations", "invitations" ], "summary": "Resend an organization invitation", "description": "Create or trigger invitations resend.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_organizations_organizationId_invitations_invitationId_resend", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Resend an organization invitation", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] }, "state": { "type": "string", "enum": [ "pending", "expired" ] } }, "required": [ "createdAt", "email", "expiresAt", "id", "role", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "invitationId path parameter" }, { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "organization:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/members": { "get": { "tags": [ "public", "organizations", "members" ], "summary": "List organization members", "description": "Fetch a specific organizations members.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_members", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "List organization members", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "members": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "membership": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "status": { "type": "string", "const": "active" } }, "required": [ "id", "joinedAt", "role", "status" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "userId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "required": [ "email", "membership", "name", "userId" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "members", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "organization:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/members/{userId}": { "delete": { "tags": [ "public", "organizations", "members" ], "summary": "Remove an organization member", "description": "Delete organizations members.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_organizations_organizationId_members_userId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Remove an organization member", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "membershipId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "removed": { "type": "boolean", "const": true }, "userId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "required": [ "membershipId", "removed", "userId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "description": "userId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "organization:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRole": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "membershipId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "required": [ "expectedRole", "membershipId" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "organizations", "members" ], "summary": "Get an organization member", "description": "Fetch a specific organizations members.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_members_userId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Get an organization member", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "membership": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "status": { "type": "string", "const": "active" } }, "required": [ "id", "joinedAt", "role", "status" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "userId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "required": [ "email", "membership", "name", "userId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "description": "userId path parameter" } ], "security": [ { "OAuth2": [ "organization:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "organizations", "members" ], "summary": "Update an organization member role", "description": "Partially update organizations members.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_organizations_organizationId_members_userId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Update an organization member role", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "membership": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "joinedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "status": { "type": "string", "const": "active" } }, "required": [ "id", "joinedAt", "role", "status" ], "additionalProperties": false }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "userId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" } }, "required": [ "email", "membership", "name", "userId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "description": "userId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "organization:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRole": { "type": "string", "enum": [ "owner", "admin", "member", "guest" ] }, "membershipId": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$" }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] } }, "required": [ "expectedRole", "membershipId", "role" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/projects": { "post": { "tags": [ "public", "projects" ], "summary": "Create a project", "description": "Create or trigger organizations projects.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_organizations_organizationId_projects", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Project created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "name": { "type": "string", "maxLength": 255 }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tier": { "type": "string", "maxLength": 50 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "isArchived", "isDefault", "name", "orgId", "tier", "timezone", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "project:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/roles": { "get": { "tags": [ "public", "organizations", "roles" ], "summary": "List assignable organization roles", "description": "Fetch a specific organizations roles.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_roles", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "List assignable organization roles", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "invitation", "member-role-change" ] }, "roles": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 50 }, "role": { "type": "string", "enum": [ "admin", "member", "guest" ] } }, "required": [ "description", "label", "role" ], "additionalProperties": false } } }, "required": [ "action", "roles" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "invitation", "member-role-change" ] }, "description": "action query parameter" } ], "security": [ { "OAuth2": [ "organization:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/organizations/{organizationId}/service-accounts": { "get": { "tags": [ "public", "service-accounts" ], "summary": "List organization service accounts", "description": "Fetch a specific organizations service-accounts.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_organizations_organizationId_service_accounts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Organization service accounts", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "serviceAccounts": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "description", "disabledAt", "id", "name", "organizationId", "status", "updatedAt" ], "additionalProperties": false } } }, "required": [ "page", "serviceAccounts" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "service-accounts" ], "summary": "Create a service account with initial project bindings", "description": "Create or trigger organizations service-accounts.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_organizations_organizationId_service_accounts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Service account created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "description", "disabledAt", "id", "name", "organizationId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bindings": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] } }, "required": [ "projectId", "role" ], "additionalProperties": false }, "uniqueItems": true }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "bindings", "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/project": { "get": { "tags": [ "public" ], "summary": "Get public project metadata", "description": "List or read public project.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_project", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Project metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "name": { "type": "string", "maxLength": 255 }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tier": { "type": "string", "maxLength": 50 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "isArchived", "isDefault", "name", "orgId", "tier", "timezone", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "context:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "description": "Required for service-account and OAuth credentials; optional for legacy keys", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] }, "patch": { "tags": [ "public", "projects" ], "summary": "Update a project", "description": "Partially update public project.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_project", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Project updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "name": { "type": "string", "maxLength": 255 }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tier": { "type": "string", "maxLength": 50 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "isArchived", "isDefault", "name", "orgId", "tier", "timezone", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Project not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "project:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/project/deletion": { "get": { "tags": [ "public", "projects", "deletion" ], "summary": "Get archive-state project deletion status", "description": "Gets archive-state project deletion status. Recovery restores archive state only and does not replay accepted telemetry.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_project_deletion", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Project deletion state", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "anyOf": [ { "type": "string", "maxLength": 96 }, { "type": "null" } ] }, "planes": { "type": "object", "properties": { "clickhouse": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "postgres": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "redis": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "s3": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] } }, "required": [ "clickhouse", "postgres", "redis", "s3" ], "additionalProperties": false }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "type": "string", "minLength": 1, "maxLength": 255 }, "purgeAfter": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoverUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "pending", "recovered", "purging", "purged", "failed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "planes", "projectId", "projectName", "purgeAfter", "recoverUntil", "runId", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "project:write" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "projects", "deletion" ], "summary": "Schedule archive-state project deletion", "description": "Schedules archive-state project deletion with a recovery window. Recovery restores archive state only and does not replay accepted telemetry. Scheduling is not activation-ready until durable accepted-event storage and fenced replay are implemented.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_project_deletion", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Project deletion state", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "anyOf": [ { "type": "string", "maxLength": 96 }, { "type": "null" } ] }, "planes": { "type": "object", "properties": { "clickhouse": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "postgres": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "redis": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "s3": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] } }, "required": [ "clickhouse", "postgres", "redis", "s3" ], "additionalProperties": false }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "type": "string", "minLength": 1, "maxLength": 255 }, "purgeAfter": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoverUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "pending", "recovered", "purging", "purged", "failed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "planes", "projectId", "projectName", "purgeAfter", "recoverUntil", "runId", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "project:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "digest", "projectId", "projectName" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "project-deletion-scheduling", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/project/deletion-preview": { "get": { "tags": [ "public", "projects", "deletion" ], "summary": "Preview archive-state project deletion", "description": "Previews archive-state project deletion with its dependency impact and recovery window. Recovery restores archive state only and does not replay accepted telemetry.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_project_deletion_preview", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded project deletion preview", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blockers": { "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "const": "service_account_last_binding" }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "code", "count" ], "additionalProperties": false } }, "counts": { "type": "object", "properties": { "apiKeys": { "type": "integer", "minimum": 0, "maximum": 10000 }, "ingestCredentials": { "type": "integer", "minimum": 0, "maximum": 10000 }, "integrations": { "type": "integer", "minimum": 0, "maximum": 10000 }, "serviceAccountBindings": { "type": "integer", "minimum": 0, "maximum": 10000 }, "traces": { "type": "object", "properties": { "capped": { "type": "boolean" }, "count": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "capped", "count" ], "additionalProperties": false } }, "required": [ "apiKeys", "ingestCredentials", "integrations", "serviceAccountBindings", "traces" ], "additionalProperties": false }, "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "blockers", "counts", "digest", "expiresAt", "projectId", "projectName" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "project:write" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/project/deletion/recover": { "post": { "tags": [ "public", "projects", "deletion" ], "summary": "Recover archive-state project deletion", "description": "Restores the project's archive state only before the recovery deadline; recovery does not replay accepted telemetry.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_project_deletion_recover", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Project deletion state", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "errorCode": { "anyOf": [ { "type": "string", "maxLength": 96 }, { "type": "null" } ] }, "planes": { "type": "object", "properties": { "clickhouse": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "postgres": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "redis": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] }, "s3": { "type": "string", "enum": [ "pending", "running", "complete", "failed", "skipped" ] } }, "required": [ "clickhouse", "postgres", "redis", "s3" ], "additionalProperties": false }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectName": { "type": "string", "minLength": 1, "maxLength": 255 }, "purgeAfter": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoverUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recoveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "pending", "recovered", "purging", "purged", "failed" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "planes", "projectId", "projectName", "purgeAfter", "recoverUntil", "runId", "state", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "project:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "projectId", "runId" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/projects": { "get": { "tags": [ "public", "projects" ], "summary": "List projects", "description": "List or read public projects.\n\n**Auth:** Requires a service-account or OAuth access Bearer token; credential scope, current bindings or memberships, tenant ownership, and entitlement are enforced without x-project-id.", "operationId": "get_api_v1_public_projects", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded project page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "projects": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "name": { "type": "string", "maxLength": 255 }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tier": { "type": "string", "maxLength": 50 }, "timezone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "access": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] } }, "required": [ "role" ], "additionalProperties": false } }, "required": [ "createdAt", "id", "isArchived", "isDefault", "name", "orgId", "tier", "timezone", "updatedAt", "access" ], "additionalProperties": false } } }, "required": [ "page", "projects" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "context:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "default": "false", "type": "string", "enum": [ "true", "false" ] }, "description": "includeArchived query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "organizationId query parameter" } ] } }, "/api/v1/public/prompts": { "get": { "tags": [ "public", "prompts" ], "summary": "List managed prompt versions", "description": "List or read public prompts.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded prompt catalog page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "prompts": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false } } }, "required": [ "page", "prompts" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "label", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "label query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "name query parameter" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 32 }, "description": "source query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "prompts" ], "summary": "Create a prompt version", "description": "Create or trigger public prompts.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_prompts", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Prompt version created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Prompt version conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "commitMessage": { "type": "string", "minLength": 1, "maxLength": 10000 }, "config": {}, "content": { "type": "string", "maxLength": 61440 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 255 }, "messages": { "minItems": 1, "maxItems": 1024, "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 61440 }, "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "default": [], "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\r\\n]+$" } }, "variables": {} }, "required": [ "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/prompts/{promptId}": { "delete": { "tags": [ "public", "prompts" ], "summary": "Delete a prompt version", "description": "Delete public prompts.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_prompts_promptId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt version deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "promptId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Active prompt cannot be deleted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "prompts" ], "summary": "Get a prompt version", "description": "Fetch a specific public prompts.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Managed prompt version", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "config": {}, "content": { "type": "string", "maxLength": 262144 }, "messages": { "anyOf": [ { "maxItems": 1024, "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 262144 }, "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, { "type": "null" } ] }, "variables": {} }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version", "config", "content", "messages", "variables" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Prompt exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/changelog": { "get": { "tags": [ "public", "prompts" ], "summary": "List prompt changelog events", "description": "Fetch a specific prompts changelog.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_changelog", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded prompt changelog page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "eventId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "fromPromptId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "label_assigned", "label_removed", "tag_added", "tag_removed", "version_created" ] }, "promptId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "commitMessage", "createdAt", "eventId", "fromPromptId", "kind", "promptId", "value", "version" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "promptName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "events", "page", "promptId", "promptName" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/comments": { "get": { "tags": [ "public", "prompts" ], "summary": "List prompt comments", "description": "Fetch a specific prompts comments.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_comments", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded prompt comment page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "comments": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "commentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content": { "type": "string", "maxLength": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "editableByCaller": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "commentId", "content", "createdAt", "editableByCaller", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "comments", "page", "promptId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 20 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "prompts" ], "summary": "Create a prompt comment", "description": "Create or trigger prompts comments.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_prompts_promptId_comments", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Prompt comment created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "commentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content": { "type": "string", "maxLength": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "editableByCaller": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "commentId", "content", "createdAt", "editableByCaller", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/comments/{commentId}": { "delete": { "tags": [ "public", "prompts" ], "summary": "Delete an owned prompt comment", "description": "Delete prompts comments.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_prompts_promptId_comments_commentId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt comment deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "commentId", "deleted" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt comment not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "commentId path parameter" }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "prompts" ], "summary": "Update an owned prompt comment", "description": "Partially update prompts comments.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_prompts_promptId_comments_commentId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt comment updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "commentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content": { "type": "string", "maxLength": 10000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "editableByCaller": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "commentId", "content", "createdAt", "editableByCaller", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt comment not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "commentId path parameter" }, { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/diff/{toPromptId}": { "get": { "tags": [ "public", "prompts" ], "summary": "Compare two prompt versions", "description": "Fetch a specific prompts diff.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_diff_toPromptId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt version diff", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changes": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "commitMessage", "config", "content", "displayName", "labels", "messages", "role", "source", "tags", "variables" ] }, "from": {}, "to": {} }, "required": [ "field", "from", "to" ], "additionalProperties": false } }, "from": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "config": {}, "content": { "type": "string", "maxLength": 262144 }, "messages": { "anyOf": [ { "maxItems": 1024, "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 262144 }, "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, { "type": "null" } ] }, "variables": {} }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version", "config", "content", "messages", "variables" ], "additionalProperties": false }, "to": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "config": {}, "content": { "type": "string", "maxLength": 262144 }, "messages": { "anyOf": [ { "maxItems": 1024, "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 262144 }, "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] } }, "required": [ "content", "role" ], "additionalProperties": false } }, { "type": "null" } ] }, "variables": {} }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version", "config", "content", "messages", "variables" ], "additionalProperties": false } }, "required": [ "changes", "from", "to" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt versions not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Prompt diff exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "toPromptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "toPromptId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/history": { "get": { "tags": [ "public", "prompts" ], "summary": "List prompt version history", "description": "Fetch a specific prompts history.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_history", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded prompt version history", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "promptName": { "type": "string", "minLength": 1, "maxLength": 255 }, "versions": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false } } }, "required": [ "page", "promptName", "versions" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/label": { "put": { "tags": [ "public", "prompts" ], "summary": "Activate a prompt label", "description": "Replace/update prompts label.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "put_api_v1_public_prompts_promptId_label", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt label activated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "label" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/labels": { "get": { "tags": [ "public", "prompts" ], "summary": "List prompt labels", "description": "Fetch a specific prompts labels.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_labels", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt labels", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "labels", "promptId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/labels/{label}": { "delete": { "tags": [ "public", "prompts" ], "summary": "Remove a prompt label", "description": "Delete prompts labels.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_prompts_promptId_labels_label", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt label removed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "label", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "description": "label path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/{promptId}/tags": { "delete": { "tags": [ "public", "prompts" ], "summary": "Remove a prompt tag", "description": "Delete prompts tags.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_prompts_promptId_tags", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt tag removed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\r\\n]+$" } }, "required": [ "tag" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "prompts" ], "summary": "List prompt tags", "description": "Fetch a specific prompts tags.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_prompts_promptId_tags", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt tags", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": [ "promptId", "tags" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "prompts" ], "summary": "Add a prompt tag", "description": "Create or trigger prompts tags.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_prompts_promptId_tags", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt tag added", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "promptId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "promptId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\r\\n]+$" } }, "required": [ "tag" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/prompts/bulk/labels": { "post": { "tags": [ "public", "prompts" ], "summary": "Activate prompt labels atomically", "description": "Create or trigger bulk labels.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_prompts_bulk_labels", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Prompt labels activated atomically", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "assignments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "changed": { "type": "boolean" }, "fromPromptId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "label": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "prompt": { "type": "object", "properties": { "commitMessage": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "displayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "labels": { "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 50 } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "source": { "type": "string", "minLength": 1, "maxLength": 32 }, "tags": { "maxItems": 128, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "commitMessage", "contentHash", "createdAt", "displayName", "id", "labels", "name", "role", "source", "tags", "updatedAt", "version" ], "additionalProperties": false } }, "required": [ "changed", "fromPromptId", "label", "prompt" ], "additionalProperties": false } }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "assignments", "schemaVersion" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Prompt not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Prompt label assignment conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Prompt label migration could not be applied", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assignments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_-]+$" }, "promptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "label", "promptId" ], "additionalProperties": false } } }, "required": [ "assignments" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/saved-filters": { "get": { "tags": [ "public", "saved-filters" ], "summary": "List saved filters", "description": "List or read public saved-filters.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_saved_filters", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded page of the current caller's saved filters", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSavedFilterListEnvelope" } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "saved-filters" ], "summary": "Create a saved filter", "description": "Create or trigger public saved-filters.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_saved_filters", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Saved filter created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Saved filter name conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSavedFilterCreateRequest" } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/saved-filters/{savedFilterId}": { "delete": { "tags": [ "public", "saved-filters" ], "summary": "Delete a saved filter", "description": "Delete public saved-filters.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_saved_filters_savedFilterId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Saved filter deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "deleted" } }, "required": [ "id", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Saved filter not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "savedFilterId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "savedFilterId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSavedFilterDeleteRequest" } } } } }, "get": { "tags": [ "public", "saved-filters" ], "summary": "Get a saved filter", "description": "Fetch a specific public saved-filters.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_saved_filters_savedFilterId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Current caller's saved trace filter", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSavedFilterEnvelope" } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Saved filter not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "savedFilterId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "savedFilterId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required OAuth user project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "saved-filters" ], "summary": "Update a saved filter", "description": "Partially update public saved-filters.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_saved_filters_savedFilterId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Saved filter updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "createdAt", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Saved filter not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Saved filter name conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "savedFilterId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "savedFilterId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSavedFilterUpdateRequest" } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/search/traces": { "post": { "tags": [ "public", "traces", "search" ], "summary": "Search traces by keyword", "description": "Read a bounded trace-search snapshot using a JSON request body. This safe POST is side-effect-free and keeps search text out of URLs and access logs.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_search_traces", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded keyword trace search page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "keyword", "semantic" ] }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "results": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "matchedSpans": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "id", "name", "type" ], "additionalProperties": false } }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "trace": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName" ], "additionalProperties": false } }, "required": [ "matchedSpans", "score", "trace" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "mode", "page", "results", "truncated" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024 }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "q": { "type": "string", "minLength": 2, "maxLength": 512 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "workflowName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "q" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/search/traces/semantic": { "post": { "tags": [ "public", "traces", "search" ], "summary": "Search traces semantically", "description": "Read a bounded semantic trace-search snapshot using a JSON request body. This safe POST is side-effect-free and keeps search text out of URLs and access logs.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "post_api_v1_public_search_traces_semantic", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded semantic trace search page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "keyword", "semantic" ] }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "results": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "matchedSpans": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "id", "name", "type" ], "additionalProperties": false } }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "trace": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName" ], "additionalProperties": false } }, "required": [ "matchedSpans", "score", "trace" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "mode", "page", "results", "truncated" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 1024 }, "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "q": { "type": "string", "minLength": 2, "maxLength": 512 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "workflowName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "q" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "always", "x-neatlogs-safe-read": true, "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/service-accounts/{serviceAccountId}": { "get": { "tags": [ "public", "service-accounts" ], "summary": "Get service-account metadata", "description": "Fetch a specific public service-accounts.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_service_accounts_serviceAccountId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "description", "disabledAt", "id", "name", "organizationId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "service-accounts" ], "summary": "Update service-account metadata", "description": "Partially update public service-accounts.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_service_accounts_serviceAccountId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service account updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "description", "disabledAt", "id", "name", "organizationId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "additionalProperties": false, "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/service-accounts/{serviceAccountId}/audit": { "get": { "tags": [ "public", "service-accounts", "audit" ], "summary": "List service-account lifecycle audit events", "description": "Fetch a specific service-accounts audit.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_service_accounts_serviceAccountId_audit", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account lifecycle audit", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "service_account.binding_created", "service_account.binding_deleted", "service_account.binding_role_updated", "service_account.created", "service_account.updated", "service_account.disabled", "service_account.token_minted", "service_account.token_revoked", "service_account.token_rotated" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "metadata": { "type": "object", "properties": { "bindingCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "predecessorTokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tokenId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "additionalProperties": false }, "resourceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resourceType": { "type": "string", "enum": [ "service_account", "service_account_project_binding", "service_account_token" ] } }, "required": [ "action", "createdAt", "id", "metadata", "resourceId", "resourceType" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "events", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/service-accounts/{serviceAccountId}/bindings": { "get": { "tags": [ "public", "service-accounts", "bindings" ], "summary": "List active service-account project bindings", "description": "Fetch a specific service-accounts bindings.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_service_accounts_serviceAccountId_bindings", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account project bindings", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "bindings": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "active" } }, "required": [ "createdAt", "id", "projectId", "role", "serviceAccountId", "status" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "bindings", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "service-accounts", "bindings" ], "summary": "Create a service-account project binding", "description": "Create or trigger service-accounts bindings.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_service_accounts_serviceAccountId_bindings", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Service-account project binding created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "active" } }, "required": [ "createdAt", "id", "projectId", "role", "serviceAccountId", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] } }, "required": [ "projectId", "role" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/service-accounts/{serviceAccountId}/bindings/{bindingId}": { "delete": { "tags": [ "public", "service-accounts", "bindings" ], "summary": "Remove a service-account project binding", "description": "Delete service-accounts bindings.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_service_accounts_serviceAccountId_bindings_bindingId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account project binding removed", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "revoked" } }, "required": [ "id", "projectId", "revokedAt", "serviceAccountId", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "bindingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "bindingId path parameter" }, { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "service-accounts", "bindings" ], "summary": "Update a service-account project binding role", "description": "Partially update service-accounts bindings.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_service_accounts_serviceAccountId_bindings_bindingId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account project binding role updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "const": "active" } }, "required": [ "createdAt", "id", "projectId", "role", "serviceAccountId", "status" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "bindingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "bindingId path parameter" }, { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "project_admin", "project_member", "project_viewer" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/service-accounts/{serviceAccountId}/disable": { "post": { "tags": [ "public", "service-accounts" ], "summary": "Disable a service account", "description": "Create or trigger service-accounts disable.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_service_accounts_serviceAccountId_disable", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service account disabled", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "description", "disabledAt", "id", "name", "organizationId", "status", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/service-accounts/{serviceAccountId}/tokens": { "get": { "tags": [ "public", "service-accounts", "tokens" ], "summary": "List all service-account token metadata", "description": "Fetch a specific service-accounts tokens.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_service_accounts_serviceAccountId_tokens", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account token metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastFour": { "type": "string", "pattern": "^[A-Za-z0-9_-]{4}$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prefix": { "type": "string", "pattern": "^nlsa_[A-Za-z0-9_-]{11}$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "rotatedFromTokenId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] }, "uniqueItems": true }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "createdAt", "expiresAt", "id", "lastFour", "lastUsedAt", "name", "prefix", "revokedAt", "rotatedFromTokenId", "scopes", "serviceAccountId", "state" ], "additionalProperties": false } } }, "required": [ "page", "tokens" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" } ], "security": [ { "OAuth2": [ "access:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "service-accounts" ], "summary": "Mint a service-account token", "description": "Create or trigger service-accounts tokens.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_service_accounts_serviceAccountId_tokens", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Service-account token minted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_service_accounts_serviceAccountId_tokens" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "null" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-][AQgw]|[A-Za-z0-9_-]{2}[AEIMQUYcgkosw048])?$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 16, "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API idempotency conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "serviceAccountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "serviceAccountId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "allOf": [ { "pattern": "^[A-Za-z0-9_-]{43}$" }, { "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } ], "writeOnly": true, "description": "Required 32-byte unpadded base64url secret replay key" }, "description": "x-neatlogs-secret-replay-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] }, "uniqueItems": true } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "service-account-token-mint", "x-contract-coverage": "contracted" } }, "/api/v1/public/sessions": { "get": { "tags": [ "public", "sessions" ], "summary": "List sessions", "description": "List or read public sessions.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_sessions", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded session page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "sessions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceName": { "type": "string", "minLength": 1, "maxLength": 255 }, "workflowName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "durationMs", "framework", "lastActivityAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "toolCallsCount", "totalCostUsd", "totalTokens", "traceCount", "traceName", "workflowName" ], "additionalProperties": false } } }, "required": [ "page", "sessions" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "from query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 }, "description": "status query parameter" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "to query parameter" }, { "name": "workflowName", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "workflowName query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/sessions/{sessionId}": { "get": { "tags": [ "public", "sessions" ], "summary": "Get a session", "description": "Fetch a specific public sessions.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_sessions_sessionId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Session metadata and trace page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "session": { "type": "object", "properties": { "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceName": { "type": "string", "minLength": 1, "maxLength": 255 }, "workflowName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "durationMs", "framework", "lastActivityAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "toolCallsCount", "totalCostUsd", "totalTokens", "traceCount", "traceName", "workflowName" ], "additionalProperties": false }, "traces": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName" ], "additionalProperties": false } } }, "required": [ "page", "session", "traces" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Session not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "sessionId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/sessions/{sessionId}/export": { "get": { "tags": [ "public", "sessions" ], "summary": "Export a session", "description": "Fetch a specific sessions export.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_sessions_sessionId_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded safe session export in JSON, Markdown, or CSV", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "session": { "type": "object", "properties": { "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceName": { "type": "string", "minLength": 1, "maxLength": 255 }, "workflowName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "durationMs", "framework", "lastActivityAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "toolCallsCount", "totalCostUsd", "totalTokens", "traceCount", "traceName", "workflowName" ], "additionalProperties": false }, "turns": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "exportStatus": { "type": "string", "enum": [ "available", "processing", "failed" ] }, "index": { "type": "integer", "minimum": 1, "maximum": 50 }, "spans": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "completionTokens", "costUsd", "durationMs", "endedAt", "model", "parentSpanId", "promptTokens", "provider", "spanId", "spanName", "spanType", "startedAt", "status", "totalTokens", "traceId" ], "additionalProperties": false } }, "trace": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName" ], "additionalProperties": false } }, "required": [ "exportStatus", "index", "spans", "trace" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "session", "turns" ], "additionalProperties": false }, { "type": "object", "properties": { "content": { "type": "string" }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "format": { "type": "string", "enum": [ "markdown", "csv" ] }, "mediaType": { "type": "string", "enum": [ "text/markdown", "text/csv" ] }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "content", "filename", "format", "mediaType", "schemaVersion" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Session not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Session export exceeds the public response budget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "sessionId path parameter" }, { "name": "format", "in": "query", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "markdown", "csv" ] }, "description": "format query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/skills": { "get": { "tags": [ "public", "skills", "configuration" ], "summary": "List evaluator skills", "description": "List or read public skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_skills", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator skills", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "skills": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1024 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "kind": { "type": "string", "const": "evaluator" }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "id", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "versionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "description", "id", "isArchived", "kind", "latestVersion", "name", "updatedAt", "versionCount" ], "additionalProperties": false } } }, "required": [ "page", "skills" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored skill page exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "default": "false", "type": "string", "enum": [ "true", "false" ] }, "description": "includeArchived query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "skills", "configuration" ], "summary": "Import a local evaluator skill", "description": "Create or trigger public skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_skills", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluator skill imported", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1024 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "kind": { "type": "string", "const": "evaluator" }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "id", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "versionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "description", "id", "isArchived", "kind", "latestVersion", "name", "updatedAt", "versionCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Skill name conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 1024 }, "markdown": { "type": "string", "minLength": 1, "maxLength": 104096 }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9-]+$" } }, "required": [ "markdown" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/skills/{skillId}": { "delete": { "tags": [ "public", "skills", "configuration" ], "summary": "Delete an evaluator skill", "description": "Delete public skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_skills_skillId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Skill deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "skillId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "skillId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Skill not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Skill is in use", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "skillId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "skills", "configuration" ], "summary": "Get an evaluator skill", "description": "Fetch a specific public skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_skills_skillId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator skill", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1024 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "kind": { "type": "string", "const": "evaluator" }, "latestVersion": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "body": { "type": "string", "minLength": 1, "maxLength": 100000 }, "contextFileCount": { "type": "integer", "minimum": 0, "maximum": 10 }, "suggestedQuestions": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000 }, "answerType": { "type": "string", "maxLength": 40 }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "required": [ "text" ], "additionalProperties": false } }, "whenToUse": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "createdAt", "id", "version", "body", "contextFileCount", "suggestedQuestions", "whenToUse" ], "additionalProperties": false }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "versionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "description", "id", "isArchived", "kind", "latestVersion", "name", "updatedAt", "versionCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Skill not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Stored skill exceeds response limits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "skillId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "skills", "configuration" ], "summary": "Update an evaluator skill", "description": "Partially update public skills.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_skills_skillId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Evaluator skill updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1024 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "kind": { "type": "string", "const": "evaluator" }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "id", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "versionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "description", "id", "isArchived", "kind", "latestVersion", "name", "updatedAt", "versionCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Skill not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "skillId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 1024 }, "isArchived": { "type": "boolean" }, "version": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 100000 }, "suggestedQuestions": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000 }, "answerType": { "type": "string", "maxLength": 40 }, "options": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "required": [ "text" ], "additionalProperties": false } }, "whenToUse": { "default": null, "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "body" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/skills/imports/github": { "post": { "tags": [ "public", "skills", "configuration" ], "summary": "Import an immutable evaluator skill from GitHub", "description": "Create or trigger imports github.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_skills_imports_github", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Evaluator skill imported from GitHub", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "description": { "type": "string", "maxLength": 1024 }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "isArchived": { "type": "boolean" }, "kind": { "type": "string", "const": "evaluator" }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "createdAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "id", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "updatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "versionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "createdAt", "description", "id", "isArchived", "kind", "latestVersion", "name", "updatedAt", "versionCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Skill name conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Remote skill content is invalid", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 8 }, "ref": { "type": "string", "pattern": "^[0-9a-fA-F]{40}$" }, "repository": { "type": "string", "minLength": 3, "maxLength": 140 }, "source": { "type": "string", "const": "github" } }, "required": [ "path", "ref", "repository", "source" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/tokens/{tokenId}": { "delete": { "tags": [ "public", "service-accounts", "tokens" ], "summary": "Revoke a service-account token", "description": "Delete public tokens.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_tokens_tokenId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Service-account token revoked", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lastFour": { "type": "string", "pattern": "^[A-Za-z0-9_-]{4}$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "prefix": { "type": "string", "pattern": "^nlsa_[A-Za-z0-9_-]{11}$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "rotatedFromTokenId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] }, "uniqueItems": true }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "createdAt", "expiresAt", "id", "lastFour", "lastUsedAt", "name", "prefix", "revokedAt", "rotatedFromTokenId", "scopes", "serviceAccountId", "state" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "tokenId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } } } }, "/api/v1/public/tokens/{tokenId}/rotate": { "post": { "tags": [ "public", "service-accounts", "tokens" ], "summary": "Rotate a service-account token", "description": "Create or trigger tokens rotate.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_tokens_tokenId_rotate", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Service-account token rotated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aad": { "type": "object", "properties": { "actorId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "actorKind": { "type": "string", "const": "user" }, "environment": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,128}$" }, "idempotencyKeyDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "operationId": { "type": "string", "const": "post_api_v1_public_tokens_tokenId_rotate" }, "orgId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "null" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "requestFingerprint": { "type": "object", "properties": { "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "keyId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "digest", "keyId", "version" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "contentType": { "type": "string", "const": "application/json" }, "schemaVersion": { "type": "number", "const": 1 }, "status": { "type": "number", "const": 201 } }, "required": [ "contentType", "schemaVersion", "status" ], "additionalProperties": false }, "version": { "type": "number", "const": 1 } }, "required": [ "actorId", "actorKind", "environment", "idempotencyKeyDigest", "operationId", "orgId", "projectId", "recordId", "requestFingerprint", "response", "version" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "A256GCM" }, "authTag": { "type": "string", "minLength": 22, "maxLength": 22, "pattern": "^[A-Za-z0-9_-]{21}[AQgw]$" }, "ciphertext": { "type": "string", "minLength": 1, "maxLength": 21846, "pattern": "^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-][AQgw]|[A-Za-z0-9_-]{2}[AEIMQUYcgkosw048])?$" }, "kind": { "type": "string", "const": "client_wrapped_secret" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 16, "pattern": "^[A-Za-z0-9_-]{16}$" }, "version": { "type": "number", "const": 1 } }, "required": [ "aad", "algorithm", "authTag", "ciphertext", "kind", "nonce", "version" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API rotation conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "tokenId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-neatlogs-secret-replay-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 43, "maxLength": 43, "allOf": [ { "pattern": "^[A-Za-z0-9_-]{43}$" }, { "pattern": "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$" } ], "writeOnly": true, "description": "Required 32-byte unpadded base64url secret replay key" }, "description": "x-neatlogs-secret-replay-key header parameter" } ], "security": [ { "OAuth2": [ "access:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] }, "uniqueItems": true } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "service-account-token-mint", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces": { "get": { "tags": [ "public", "traces" ], "summary": "List traces", "description": "List or read public traces.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded trace page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "traces": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName" ], "additionalProperties": false } } }, "required": [ "page", "traces" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "from query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 }, "description": "status query parameter" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "description": "to query parameter" }, { "name": "workflowName", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "workflowName query parameter" }, { "name": "sessionId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "sessionId query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/traces/{traceId}": { "delete": { "tags": [ "public", "traces" ], "summary": "Soft-delete a trace", "description": "Delete public traces.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_traces_traceId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Trace catalog entry soft-deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deletedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "mode": { "type": "string", "const": "soft_delete" }, "publicSharingRevoked": { "type": "boolean", "const": true }, "state": { "type": "string", "const": "deleted" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "deletedAt", "mode", "publicSharingRevoked", "state", "traceId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:write" ] } ], "x-neatlogs-operation-gate": "tier-c-compute", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "traces" ], "summary": "Get a trace", "description": "Fetch a specific public traces.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Safe trace metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "metadataRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadataUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName", "metadataRevision", "metadataUpdatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "traces" ], "summary": "Update trace metadata", "description": "Partially update public traces.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_traces_traceId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Trace metadata updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "metadataRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadataUpdatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "changedFields": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "tags", "traceName" ] } } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName", "metadataRevision", "metadataUpdatedAt", "changedFields" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace metadata revision conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tags": { "anyOf": [ { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "type": "null" } ] }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "expectedRevision" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/comment-threads": { "get": { "tags": [ "public", "comments" ], "summary": "List trace comment threads", "description": "Fetch a specific traces comment-threads.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_comment_threads", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded comment-thread page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "threads": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "isResolved": { "type": "boolean" }, "lastMessageAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "target": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "itemKey": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ] }, "spanName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "trace", "agent", "span", "item" ] } }, "required": [ "id", "itemKey", "spanId", "spanName", "type" ], "additionalProperties": false }, "threadId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "createdAt", "isResolved", "lastMessageAt", "messageCount", "target", "threadId", "traceId", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "threads", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "resolved", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "resolved query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/comment-threads/{threadId}": { "get": { "tags": [ "public", "comments" ], "summary": "Get trace comment thread", "description": "Fetch a specific traces comment-threads.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_comment_threads_threadId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Comment thread with a bounded message page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "messages": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "content": { "type": "string" }, "contentTruncated": { "type": "boolean" }, "context": { "type": "object", "properties": { "replyToMessageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "selectedSectionType": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "replyToMessageId", "selectedSectionType" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "messageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reactions": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "emoji": { "type": "string", "minLength": 1, "maxLength": 64 }, "reactedByCaller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "count", "emoji", "reactedByCaller" ], "additionalProperties": false } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "content", "contentTruncated", "context", "createdAt", "messageId", "reactions", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "thread": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "isResolved": { "type": "boolean" }, "lastMessageAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "target": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "itemKey": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "spanId": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ] }, "spanName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "trace", "agent", "span", "item" ] } }, "required": [ "id", "itemKey", "spanId", "spanName", "type" ], "additionalProperties": false }, "threadId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "createdAt", "isResolved", "lastMessageAt", "messageCount", "target", "threadId", "traceId", "updatedAt" ], "additionalProperties": false } }, "required": [ "messages", "page", "thread" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Comment thread not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "threadId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/comment-threads/{threadId}/messages": { "post": { "tags": [ "public", "comments" ], "summary": "Create a trace comment", "description": "Create or trigger comment-threads messages.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_traces_traceId_comment_threads_threadId_messages", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Comment created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "content": { "type": "string" }, "contentTruncated": { "type": "boolean" }, "context": { "type": "object", "properties": { "replyToMessageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "selectedSectionType": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "replyToMessageId", "selectedSectionType" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "messageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reactions": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "emoji": { "type": "string", "minLength": 1, "maxLength": 64 }, "reactedByCaller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "count", "emoji", "reactedByCaller" ], "additionalProperties": false } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "content", "contentTruncated", "context", "createdAt", "messageId", "reactions", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Comment thread not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "threadId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Non-empty comment text of at most 10000 UTF-8 bytes." } }, "required": [ "content" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/comment-threads/{threadId}/messages/{messageId}": { "delete": { "tags": [ "public", "comments" ], "summary": "Delete an owned trace comment", "description": "Delete comment-threads messages.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_traces_traceId_comment_threads_threadId_messages_messageId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Comment deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "messageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "messageId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Comment not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "messageId path parameter" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "threadId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "patch": { "tags": [ "public", "comments" ], "summary": "Update an owned trace comment", "description": "Partially update comment-threads messages.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_traces_traceId_comment_threads_threadId_messages_messageId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Comment updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "content": { "type": "string" }, "contentTruncated": { "type": "boolean" }, "context": { "type": "object", "properties": { "replyToMessageId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "selectedSectionType": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] } }, "required": [ "replyToMessageId", "selectedSectionType" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "messageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reactions": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "emoji": { "type": "string", "minLength": 1, "maxLength": 64 }, "reactedByCaller": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "count", "emoji", "reactedByCaller" ], "additionalProperties": false } }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "authorDisplayName", "content", "contentTruncated", "context", "createdAt", "messageId", "reactions", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Comment not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "messageId path parameter" }, { "name": "threadId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "threadId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "description": "Non-empty comment text of at most 10000 UTF-8 bytes." } }, "required": [ "content" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/evaluations": { "get": { "tags": [ "public", "evaluations", "traces" ], "summary": "List evaluations associated with a trace", "description": "Fetch a specific traces evaluations.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_traces_traceId_evaluations", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded trace evaluation associations", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "associations": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "addedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "evaluation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 50 } }, "required": [ "id", "name", "type" ], "additionalProperties": false }, "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "minLength": 1, "maxLength": 50 }, "target": { "oneOf": [ { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemType": { "type": "string", "const": "trace" }, "parentTraceId": { "type": "null" }, "spanId": { "type": "null" }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "itemId", "itemType", "parentTraceId", "spanId", "traceId" ], "additionalProperties": false }, { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "itemType": { "type": "string", "const": "span" }, "parentTraceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "itemId", "itemType", "parentTraceId", "spanId", "traceId" ], "additionalProperties": false } ] } }, "required": [ "addedAt", "evaluation", "itemId", "status", "target" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "associations", "truncated" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "evaluation:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/export": { "get": { "tags": [ "public", "traces" ], "summary": "Export a trace", "description": "Fetch a specific traces export.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_export", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded safe trace export in JSON, Markdown, or CSV", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "spans": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "completionTokens", "costUsd", "durationMs", "endedAt", "model", "parentSpanId", "promptTokens", "provider", "spanId", "spanName", "spanType", "startedAt", "status", "totalTokens", "traceId" ], "additionalProperties": false } }, "trace": { "type": "object", "properties": { "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "finalizationStatus": { "anyOf": [ { "type": "string", "enum": [ "pending", "finalized", "dlq" ] }, { "type": "null" } ] }, "framework": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "ingestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "llmCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sessionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "spansCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "toolCallsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "totalCostUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "traceName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workflowName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "metadataRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadataUpdatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "completedAt", "durationMs", "finalizationStatus", "framework", "ingestedAt", "llmCallsCount", "sessionId", "spansCount", "startedAt", "status", "tags", "toolCallsCount", "totalCostUsd", "totalTokens", "traceId", "traceName", "workflowName", "metadataRevision", "metadataUpdatedAt" ], "additionalProperties": false } }, "required": [ "schemaVersion", "spans", "trace" ], "additionalProperties": false }, { "type": "object", "properties": { "content": { "type": "string" }, "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "format": { "type": "string", "enum": [ "markdown", "csv" ] }, "mediaType": { "type": "string", "enum": [ "text/markdown", "text/csv" ] }, "schemaVersion": { "type": "number", "const": 1 } }, "required": [ "content", "filename", "format", "mediaType", "schemaVersion" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "422": { "description": "Trace export exceeds the public response budget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 422, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "format", "in": "query", "required": false, "schema": { "default": "json", "type": "string", "enum": [ "json", "markdown", "csv" ] }, "description": "format query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/feedback": { "get": { "tags": [ "public", "feedback" ], "summary": "List trace feedback", "description": "Fetch a specific traces feedback.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded trace feedback page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "feedback": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "contentTruncated": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 65536 UTF-8 bytes." }, { "type": "null" } ] }, "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "accuracy", "authorDisplayName", "comment", "contentTruncated", "createdAt", "expectedResponse", "feedbackId", "issueTypes", "rating", "traceId", "updatedAt" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "feedback", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "post": { "tags": [ "public", "feedback" ], "summary": "Create trace feedback", "description": "Create or trigger traces feedback.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_traces_traceId_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Trace feedback created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "contentTruncated": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 65536 UTF-8 bytes." }, { "type": "null" } ] }, "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "accuracy", "authorDisplayName", "comment", "contentTruncated", "createdAt", "expectedResponse", "feedbackId", "issueTypes", "rating", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 50 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 16384 UTF-8 bytes." }, { "type": "null" } ] }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/feedback/{feedbackId}": { "delete": { "tags": [ "public", "feedback" ], "summary": "Delete owned trace feedback", "description": "Delete traces feedback.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_traces_traceId_feedback_feedbackId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Trace feedback deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "feedbackId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Feedback not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "feedbackId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "feedbackId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "feedback" ], "summary": "Get trace feedback", "description": "Fetch a specific traces feedback.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_feedback_feedbackId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Sanitized feedback", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "contentTruncated": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 65536 UTF-8 bytes." }, { "type": "null" } ] }, "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "accuracy", "authorDisplayName", "comment", "contentTruncated", "createdAt", "expectedResponse", "feedbackId", "issueTypes", "rating", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Feedback not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "feedbackId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "feedbackId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "feedback" ], "summary": "Update owned trace feedback", "description": "Partially update traces feedback.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_traces_traceId_feedback_feedbackId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Trace feedback updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "authorDisplayName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "contentTruncated": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 65536 UTF-8 bytes." }, { "type": "null" } ] }, "feedbackId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "accuracy", "authorDisplayName", "comment", "contentTruncated", "createdAt", "expectedResponse", "feedbackId", "issueTypes", "rating", "traceId", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Feedback not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "feedbackId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "feedbackId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accuracy": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 50 }, { "type": "null" } ] }, "comment": { "anyOf": [ { "type": "string", "description": "At most 16384 UTF-8 bytes." }, { "type": "null" } ] }, "expectedResponse": { "anyOf": [ { "type": "string", "description": "At most 32768 UTF-8 bytes." }, { "type": "null" } ] }, "issueTypes": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "rating": { "anyOf": [ { "type": "integer", "minimum": -100, "maximum": 100 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/raw-spans": { "get": { "tags": [ "public", "spans" ], "summary": "List raw span previews", "description": "Fetch a specific traces raw-spans.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_raw_spans", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded raw span previews", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "spans": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "error": { "type": "object", "properties": { "messagePreview": { "type": "string" }, "truncated": { "type": "boolean" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "messagePreview", "truncated", "type" ], "additionalProperties": false }, "input": { "type": "object", "properties": { "mimeType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "preview": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "mimeType", "preview", "truncated" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "mimeType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "preview": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "mimeType", "preview", "truncated" ], "additionalProperties": false }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "durationMs", "endedAt", "error", "input", "output", "parentSpanId", "spanId", "spanName", "spanType", "startedAt", "status", "traceId" ], "additionalProperties": false } } }, "required": [ "page", "spans" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 }, "description": "status query parameter" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "type query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/sharing": { "get": { "tags": [ "public", "sharing", "traces" ], "summary": "Get trace-sharing status", "description": "Fetch a specific traces sharing.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_traces_traceId_sharing", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted trace-sharing status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "disabled", "expired" ] }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "enabled", "expiresAt", "state", "traceId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "sharing:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/span-feedback": { "get": { "tags": [ "public", "feedback" ], "summary": "List trace span feedback", "description": "Fetch a specific traces span-feedback.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_span_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded span feedback page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "feedback": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "callerVote": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "downCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "upCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "callerVote", "downCount", "spanId", "upCount" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "feedback", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/spans": { "get": { "tags": [ "public", "spans" ], "summary": "List trace spans", "description": "Fetch a specific traces spans.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_spans", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded safe span page", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false }, "spans": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "completionTokens", "costUsd", "durationMs", "endedAt", "model", "parentSpanId", "promptTokens", "provider", "spanId", "spanName", "spanType", "startedAt", "status", "totalTokens", "traceId" ], "additionalProperties": false } } }, "required": [ "page", "spans" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Trace not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "limit query parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 20 }, "description": "status query parameter" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "type query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/spans/{spanId}": { "get": { "tags": [ "public", "spans" ], "summary": "Get a trace span", "description": "Fetch a specific traces spans.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_spans_spanId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Safe span metadata", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costUsd": { "type": "number", "minimum": 0, "maximum": 1000000000000 }, "durationMs": { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parentSpanId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "spanName": { "type": "string", "minLength": 1, "maxLength": 255 }, "spanType": { "type": "string", "minLength": 1, "maxLength": 50 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "status": { "type": "string", "minLength": 1, "maxLength": 20 }, "totalTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "completionTokens", "costUsd", "durationMs", "endedAt", "model", "parentSpanId", "promptTokens", "provider", "spanId", "spanName", "spanType", "startedAt", "status", "totalTokens", "traceId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Span not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "spanId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "spanId path parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/spans/{spanId}/feedback": { "delete": { "tags": [ "public", "feedback" ], "summary": "Delete caller span feedback", "description": "Delete spans feedback.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_traces_traceId_spans_spanId_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Span feedback deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callerVote": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "downCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "upCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "callerVote", "downCount", "spanId", "upCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Span feedback not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "spanId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "spanId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "feedback" ], "summary": "Get trace span feedback", "description": "Fetch a specific spans feedback.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_spans_spanId_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Sanitized span feedback", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callerVote": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "downCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "upCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "callerVote", "downCount", "spanId", "upCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Span not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "spanId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "spanId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "put": { "tags": [ "public", "feedback" ], "summary": "Set caller span feedback", "description": "Replace/update spans feedback.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "put_api_v1_public_traces_traceId_spans_spanId_feedback", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Span feedback set", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "callerVote": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "downCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "upCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "callerVote", "downCount", "spanId", "upCount" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Span not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "spanId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "spanId path parameter" }, { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "observability:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "anyOf": [ { "type": "string", "description": "At most 2048 UTF-8 bytes." }, { "type": "null" } ] }, "vote": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "vote" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/traces/{traceId}/spans/{spanId}/payload": { "get": { "tags": [ "public", "spans" ], "summary": "Get selected span payload fields", "description": "Fetch a specific spans payload.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_traces_traceId_spans_spanId_payload", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Selected span payload fields", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fields": { "type": "object", "properties": { "error": { "type": "object", "properties": { "available": { "type": "boolean" }, "mimeType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "available", "mimeType", "truncated", "value" ], "additionalProperties": false }, "input": { "type": "object", "properties": { "available": { "type": "boolean" }, "mimeType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "available", "mimeType", "truncated", "value" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "available": { "type": "boolean" }, "mimeType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "available", "mimeType", "truncated", "value" ], "additionalProperties": false } }, "additionalProperties": false }, "spanId": { "type": "string", "minLength": 1, "maxLength": 128 }, "traceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fields", "spanId", "traceId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Span payload not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Trace projection is not ready", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "traceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "traceId path parameter" }, { "name": "spanId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "spanId path parameter" }, { "name": "fields", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "error", "input", "output", "error,input", "error,output", "input,error", "input,output", "output,error", "output,input", "error,input,output", "error,output,input", "input,error,output", "input,output,error", "output,error,input", "output,input,error" ] }, "description": "fields query parameter" }, { "name": "x-project-id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "observability:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/webhooks": { "get": { "tags": [ "public", "webhooks", "configuration" ], "summary": "List redacted webhook configurations", "description": "List or read public webhooks.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_webhooks", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Bounded redacted webhook configurations", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "truncated": { "type": "boolean" }, "webhooks": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "destinationConfigured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "eventTypes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "destinationConfigured", "enabled", "eventTypes", "id", "name", "updatedAt" ], "additionalProperties": false } } }, "required": [ "truncated", "webhooks" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ] }, "post": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Create a webhook", "description": "Create or trigger public webhooks.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_webhooks", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "201": { "description": "Webhook created", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "destinationConfigured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "eventTypes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "destinationConfigured", "enabled", "eventTypes", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Webhook conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destinationUrl": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "eventTypes": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "secret": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "writeOnly": true }, { "type": "null" } ] } }, "required": [ "destinationUrl", "eventTypes", "name" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "parameters": [ { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } }, "/api/v1/public/webhooks/{webhookId}": { "delete": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Delete a webhook", "description": "Delete public webhooks.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "delete_api_v1_public_webhooks_webhookId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Webhook deleted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "deleted", "webhookId" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } }, "get": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Get redacted webhook configuration", "description": "Fetch a specific public webhooks.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_webhooks_webhookId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted webhook configuration", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "destinationConfigured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "eventTypes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "destinationConfigured", "enabled", "eventTypes", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" }, "patch": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Update a webhook", "description": "Partially update public webhooks.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "patch_api_v1_public_webhooks_webhookId", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Webhook updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "destinationConfigured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "eventTypes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "destinationConfigured", "enabled", "eventTypes", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Webhook conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "destinationUrl": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "eventTypes": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "secret": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "writeOnly": true }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "public", "webhooks", "configuration" ], "summary": "List redacted webhook delivery history", "description": "Fetch a specific webhooks deliveries.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "get_api_v1_public_webhooks_webhookId_deliveries", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Redacted webhook delivery history", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveries": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "deliveredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "eventType": { "type": "string", "minLength": 1, "maxLength": 100 }, "httpStatus": { "anyOf": [ { "type": "object", "properties": { "class": { "type": "string", "enum": [ "1xx", "2xx", "3xx", "4xx", "5xx" ] }, "code": { "type": "integer", "minimum": 100, "maximum": 599 } }, "required": [ "class", "code" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "latencyMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "outcome": { "type": "string", "enum": [ "connection_failed", "failed", "succeeded" ] } }, "required": [ "attempt", "deliveredAt", "eventType", "httpStatus", "id", "latencyMs", "outcome" ], "additionalProperties": false } }, "page": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ] } }, "required": [ "hasMore", "limit", "nextCursor" ], "additionalProperties": false } }, "required": [ "deliveries", "page" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "cursor query parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "limit query parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Required service-account or OAuth project selection" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted" } }, "/api/v1/public/webhooks/{webhookId}/deliveries/{deliveryId}/replay": { "post": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Replay a stored webhook delivery", "description": "Create or trigger deliveries replay.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_webhooks_webhookId_deliveries_deliveryId_replay", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Webhook replay accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "deliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "test" }, "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "accepted", "deliveryId", "kind", "webhookId" ], "additionalProperties": false }, { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "deliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "replay" }, "sourceDeliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "accepted", "deliveryId", "kind", "sourceDeliveryId", "webhookId" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook delivery not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "deliveryId path parameter" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/webhooks/{webhookId}/status": { "post": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Set webhook state", "description": "Create or trigger webhooks status.\n\n**Auth:** Requires a service-account or OAuth access Bearer token and explicit x-project-id; credential scope, current project role, tenant ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_webhooks_webhookId_status", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Webhook state updated", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "destinationConfigured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "eventTypes": { "maxItems": 64, "type": "array", "items": { "type": "string", "enum": [ "*", "alert.anomaly_detected", "alert.compound_breach", "alert.ingestion_silent", "alert.metric_threshold_breach", "alert.per_event_match", "alert.sla_breach_warning", "alert.threshold_breach", "notification.action_items", "notification.approval_approved", "notification.approval_expired", "notification.approval_rejected", "notification.approval_requested", "notification.backfill_completed", "notification.classifier_trained", "notification.comment_created", "notification.daily_digest", "notification.experiment_significant", "notification.mention", "notification.prompt_version_changed", "notification.weekly_report", "notify.eval_assigned", "notify.eval_batch_deadline_passed", "notify.eval_batch_dispatched", "notify.eval_completed", "notify.eval_deadline_approaching", "notify.eval_deadline_passed", "notify.eval_reminder", "notify.eval_response_submitted", "ops.trace_finalizer_scaled" ] } }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "createdAt", "destinationConfigured", "enabled", "eventTypes", "id", "name", "updatedAt" ], "additionalProperties": false }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/webhooks/{webhookId}/test": { "post": { "tags": [ "public", "webhooks", "configuration" ], "summary": "Send a bounded test webhook", "description": "Create or trigger webhooks test.\n\n**Auth:** Requires an OAuth access Bearer token for a current NeatLogs user; current tenant RBAC, scope, resource ownership, and entitlement are enforced.", "operationId": "post_api_v1_public_webhooks_webhookId_test", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "202": { "description": "Webhook test accepted", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "deliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "test" }, "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "accepted", "deliveryId", "kind", "webhookId" ], "additionalProperties": false }, { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "deliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "replay" }, "sourceDeliveryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "webhookId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "accepted", "deliveryId", "kind", "sourceDeliveryId", "webhookId" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "webhookId path parameter" }, { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 22, "maxLength": 43, "pattern": "^(?:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|[A-Za-z0-9_-]{21}[AQgw]|[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$", "description": "Required canonical UUIDv4 or high-entropy base64url idempotency key" }, "description": "idempotency-key header parameter" }, { "name": "x-project-id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ], "security": [ { "OAuth2": [ "configuration:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } }, "x-neatlogs-operation-gate": "public-api-mutations", "x-contract-coverage": "contracted" } }, "/api/v1/public/whoami": { "get": { "tags": [ "public" ], "summary": "Get the authenticated Public API actor context", "description": "List or read public whoami.\n\n**Auth:** Requires a legacy project-bound public API key, service-account Bearer token, or OAuth access Bearer token; each credential follows its own carrier and authorization policy.", "operationId": "get_api_v1_public_whoami", "x-auth-gate": "public-api-key", "x-auth-source": "global-gate", "responses": { "200": { "description": "Authenticated actor and resolved authorization context", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "legacy_public_api_key" } }, "required": [ "id", "kind" ], "additionalProperties": false }, "authorizationModelVersion": { "type": "number", "const": 1 }, "context": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "basis": { "type": "string", "const": "legacy_scope_binding" }, "effectivePermissions": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "const": "project:read" } } }, "required": [ "basis", "effectivePermissions" ], "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "authorization", "organizationId", "projectId" ], "additionalProperties": false }, "credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "legacy_public_api_key" }, "scopes": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "const": "project:read" } } }, "required": [ "id", "kind", "scopes" ], "additionalProperties": false } }, "required": [ "actor", "authorizationModelVersion", "context", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "service_account" } }, "required": [ "id", "kind" ], "additionalProperties": false }, "authorizationModelVersion": { "type": "number", "const": 1 }, "context": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "basis": { "type": "string", "const": "service_account_project_binding" }, "effectivePermissions": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "const": "project:read" } } }, "required": [ "basis", "effectivePermissions" ], "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "authorization", "organizationId", "projectId" ], "additionalProperties": false }, "credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "service_account" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] } }, "serviceAccountId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "kind", "scopes", "serviceAccountId" ], "additionalProperties": false } }, "required": [ "actor", "authorizationModelVersion", "context", "credential" ], "additionalProperties": false }, { "type": "object", "properties": { "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "user" } }, "required": [ "id", "kind" ], "additionalProperties": false }, "authorizationModelVersion": { "type": "number", "const": 1 }, "context": { "type": "object", "properties": { "authorization": { "type": "object", "properties": { "basis": { "type": "string", "const": "oauth_user_rbac" }, "effectivePermissions": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "const": "project:read" } } }, "required": [ "basis", "effectivePermissions" ], "additionalProperties": false }, "organizationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "authorization", "organizationId", "projectId" ], "additionalProperties": false }, "credential": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "kind": { "type": "string", "const": "oauth_access_token" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "context:read", "project:write", "organization:read", "organization:write", "billing:read", "profile:read", "profile:write", "observability:read", "observability:write", "evaluation:read", "evaluation:write", "configuration:read", "configuration:write", "sharing:read", "sharing:write", "access:read", "access:write" ] } } }, "required": [ "id", "kind", "scopes" ], "additionalProperties": false } }, "required": [ "actor", "authorizationModelVersion", "context", "credential" ], "additionalProperties": false } ] }, "requestId": { "type": "string", "pattern": "^req_[a-f0-9]{32}$" }, "success": { "type": "boolean", "const": true } }, "required": [ "data", "requestId", "success" ], "additionalProperties": false } } } }, "400": { "description": "Invalid public API request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 400, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "401": { "description": "Missing or invalid public API credential", "headers": { "WWW-Authenticate": { "$ref": "#/components/headers/PublicApiWwwAuthenticate" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 401, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "403": { "description": "Public API request is not authorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 403, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "404": { "description": "Public API resource not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 404, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "409": { "description": "Public API request conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 409, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "413": { "description": "Public API request body too large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 413, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "415": { "description": "Unsupported public API request body", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 415, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "429": { "description": "Public API rate limit exceeded", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/PublicApiRateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiRateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/PublicApiRateLimitReset" }, "X-NeatLogs-RateLimit-Degraded": { "$ref": "#/components/headers/PublicApiRateLimitDegraded" }, "X-NeatLogs-RateLimit-Limit": { "$ref": "#/components/headers/PublicApiLegacyRateLimitLimit" }, "X-NeatLogs-RateLimit-Policy": { "$ref": "#/components/headers/PublicApiRateLimitPolicy" }, "X-NeatLogs-RateLimit-Remaining": { "$ref": "#/components/headers/PublicApiLegacyRateLimitRemaining" }, "X-NeatLogs-RateLimit-Reset-After": { "$ref": "#/components/headers/PublicApiRateLimitResetAfter" }, "X-NeatLogs-RateLimit-Version": { "$ref": "#/components/headers/PublicApiRateLimitVersion" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" }, "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 429, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "500": { "description": "Internal server error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 500, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } } } }, "503": { "description": "Public API credential, project context, or rate limiting unavailable. Backend is draining; retry after the Retry-After delay.", "headers": { "Retry-After": { "$ref": "#/components/headers/PublicApiRetryAfter" }, "X-Request-Id": { "$ref": "#/components/headers/PublicApiRequestId" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PublicApiProblem" }, { "properties": { "status": { "const": 503, "type": "number" } }, "required": [ "status" ], "type": "object" } ] } }, "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Backend is draining" } }, "required": [ "error" ], "additionalProperties": false } } } } }, "security": [ { "PublicApiKeyAuth": [] }, { "PublicApiLegacyBearerAuth": [] }, { "ServiceAccountBearerAuth": [] }, { "OAuth2": [ "context:read" ] } ], "x-neatlogs-operation-gate": "always", "x-contract-coverage": "contracted", "parameters": [ { "name": "x-project-id", "in": "header", "required": false, "schema": { "description": "Required for service-account and OAuth credentials; optional for legacy keys", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "description": "x-project-id header parameter" } ] } } } }