{
    "contract": "spiralist-public-api-v2",
    "apiVersion": "2.0.0",
    "documentationVersion": "2.0.0",
    "problemContract": "spiralist-problem-details-v2",
    "release": "v100.0.20-npc-quality-research-integration-wip",
    "packageStatus": "work-in-progress",
    "completionMarker": "SPIRALIST_ECONOMY_HOUSING_SOURCE_REVIEW_WIP_V100_0_19",
    "state": "stateless-unless-a-specific-route-documents-otherwise",
    "idempotencyMode": "correlation-only",
    "promptSeparation": {
        "promptsAreSeparate": true,
        "personaPromptContract": "separate-persona-and-safety-prompts-v1",
        "platformSafetyOverlayVersion": "1.0.0",
        "platformSafetyRemoved": false,
        "hostPlatformSafetyUnchanged": true,
        "uaixBoundary": "persona-only-runtime-overlay-excluded-v1",
        "uaixIncludesPlatformSafety": false,
        "meaning": "The separately authored Spiralist platform overlay may be exported only as a separate non-UAIX file. Host and provider enforcement remain unchanged."
    },
    "maximumAdminBatchPersonasPerRequest": 25,
    "endpoints": [
        {
            "path": "/api/v1/contract/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Public API contract discovery."
        },
        {
            "path": "/api/v1/endpoints/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Endpoint inventory."
        },
        {
            "path": "/api/v1/examples/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Copy-ready request examples."
        },
        {
            "path": "/api/v1/problems/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Typed problem catalog."
        },
        {
            "path": "/api/v1/headers/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Request and response header reference."
        },
        {
            "path": "/api/v1/standards/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Standards and limitations."
        },
        {
            "path": "/api/v1/schemas/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Schema inventory."
        },
        {
            "path": "/api/v1/changelog/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "API contract changes."
        },
        {
            "path": "/api/v1/openapi/validation/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Non-generating OpenAPI mirror validation summary."
        },
        {
            "path": "/api/v1/admin/batch-personas/",
            "methods": [
                "GET",
                "HEAD",
                "POST",
                "OPTIONS"
            ],
            "purpose": "Bounded server-side persona generation used by the admin batch exporter."
        },
        {
            "path": "/api/v1/create/standard/random/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Random standard persona."
        },
        {
            "path": "/api/v1/create/psychosis/random/",
            "methods": [
                "GET",
                "HEAD",
                "POST",
                "OPTIONS"
            ],
            "purpose": "Adult fictional psychosis character."
        },
        {
            "path": "/api/v1/create/espionage/random/",
            "methods": [
                "GET",
                "HEAD",
                "POST",
                "OPTIONS"
            ],
            "purpose": "Adult fictional espionage persona."
        },
        {
            "path": "/api/v1/create/espionage-psychosis/random/",
            "methods": [
                "GET",
                "HEAD",
                "POST",
                "OPTIONS"
            ],
            "purpose": "Adult fictional Espionage Psychosis character."
        },
        {
            "path": "/api/v1/create/adult/status/",
            "methods": [
                "GET",
                "HEAD",
                "OPTIONS"
            ],
            "purpose": "Fresh deployment and component verification."
        }
    ],
    "headers": {
        "request": {
            "Accept": "Desired response media type.",
            "Accept-Version": "Compatible alias for the requested API version.",
            "X-Spiralist-Api-Version": "Requested Spiralist public API version.",
            "Content-Type": "Use application/json for JSON request bodies.",
            "Idempotency-Key": "Validated correlation key. Durable replay is not yet promised.",
            "X-Spiralist-Client": "Optional public integration identifier.",
            "X-Spiralist-Trace-Id": "Optional caller trace identifier matching the documented token pattern.",
            "Authorization": "Optional administrator Basic or Bearer credential when configured.",
            "X-Spiralist-Admin-Token": "Optional administrator token when configured."
        },
        "response": {
            "X-Request-Id": "Request identifier.",
            "X-Spiralist-Request-Id": "Spiralist request identifier.",
            "X-Spiralist-Trace-Id": "Trace identifier.",
            "X-Spiralist-Api-Contract": "spiralist-public-api-v2",
            "X-Spiralist-Api-Version": "2.0.0",
            "X-Spiralist-Documentation-Version": "2.0.0",
            "X-Spiralist-Problem-Contract": "spiralist-problem-details-v2",
            "X-Spiralist-Idempotency-Status": "correlation-only",
            "Content-Digest": "RFC 9530 SHA-256 digest of the transferred representation.",
            "X-Spiralist-Content-Sha256": "Lowercase hexadecimal SHA-256 digest.",
            "X-Spiralist-Request-Duration-Ms": "Server-side request duration.",
            "Server-Timing": "Server-side application duration.",
            "RateLimit": "Compact rate-limit state.",
            "RateLimit-Limit": "Request limit for the current window.",
            "RateLimit-Remaining": "Remaining requests in the current window.",
            "RateLimit-Reset": "Seconds until reset.",
            "RateLimit-Policy": "Limit and window policy.",
            "Link": "Documentation, schema, discovery, and OpenAPI relationships."
        }
    },
    "problemTypes": {
        "INVALID_JSON": {
            "code": "INVALID_JSON",
            "status": 400,
            "type": "https://spiralistai.com/problems/invalid-json",
            "detail": "The request body is not valid JSON."
        },
        "JSON_OBJECT_REQUIRED": {
            "code": "JSON_OBJECT_REQUIRED",
            "status": 422,
            "type": "https://spiralistai.com/problems/json-object-required",
            "detail": "The JSON document is valid but is not an object."
        },
        "UNSUPPORTED_MEDIA_TYPE": {
            "code": "UNSUPPORTED_MEDIA_TYPE",
            "status": 415,
            "type": "https://spiralistai.com/problems/unsupported-media-type",
            "detail": "The request Content-Type is not supported."
        },
        "NOT_ACCEPTABLE": {
            "code": "NOT_ACCEPTABLE",
            "status": 406,
            "type": "https://spiralistai.com/problems/not-acceptable",
            "detail": "The requested response media type is not available."
        },
        "UNSUPPORTED_API_VERSION": {
            "code": "UNSUPPORTED_API_VERSION",
            "status": 400,
            "type": "https://spiralistai.com/problems/unsupported-api-version",
            "detail": "The requested API version is not supported."
        },
        "INVALID_IDEMPOTENCY_KEY": {
            "code": "INVALID_IDEMPOTENCY_KEY",
            "status": 400,
            "type": "https://spiralistai.com/problems/invalid-idempotency-key",
            "detail": "The Idempotency-Key syntax is invalid."
        },
        "AGE_CONFIRMATION_REQUIRED": {
            "code": "AGE_CONFIRMATION_REQUIRED",
            "status": 403,
            "type": "https://spiralistai.com/problems/age-confirmation-required",
            "detail": "Explicit adult confirmation is required."
        },
        "ADMIN_AUTHENTICATION_REQUIRED": {
            "code": "ADMIN_AUTHENTICATION_REQUIRED",
            "status": 401,
            "type": "https://spiralistai.com/problems/admin-authentication-required",
            "detail": "The configured admin credential was not supplied."
        },
        "INVALID_PERSONA_TYPE": {
            "code": "INVALID_PERSONA_TYPE",
            "status": 422,
            "type": "https://spiralistai.com/problems/invalid-persona-type",
            "detail": "The requested persona family is unknown."
        },
        "INVALID_RUNTIME_MODE": {
            "code": "INVALID_RUNTIME_MODE",
            "status": 422,
            "type": "https://spiralistai.com/problems/invalid-runtime-mode",
            "detail": "The requested assistant or NPC runtime mode is unknown."
        },
        "INVALID_EXPORT_FORMAT": {
            "code": "INVALID_EXPORT_FORMAT",
            "status": 422,
            "type": "https://spiralistai.com/problems/invalid-export-format",
            "detail": "One or more requested export formats are unsupported."
        },
        "INVALID_BATCH_SIZE": {
            "code": "INVALID_BATCH_SIZE",
            "status": 422,
            "type": "https://spiralistai.com/problems/invalid-batch-size",
            "detail": "The server-side batch count is outside the documented range."
        },
        "UAIX_PLATFORM_SAFETY_FORBIDDEN": {
            "code": "UAIX_PLATFORM_SAFETY_FORBIDDEN",
            "status": 422,
            "type": "https://spiralistai.com/problems/uaix-platform-safety-forbidden",
            "detail": "A persona UAI package contains forbidden platform-overlay data."
        },
        "RATE_LIMITED": {
            "code": "RATE_LIMITED",
            "status": 429,
            "type": "https://spiralistai.com/problems/rate-limited",
            "detail": "The route request budget has been exceeded."
        },
        "METHOD_NOT_ALLOWED": {
            "code": "METHOD_NOT_ALLOWED",
            "status": 405,
            "type": "https://spiralistai.com/problems/method-not-allowed",
            "detail": "The HTTP method is not supported by this route."
        },
        "REQUEST_TOO_LARGE": {
            "code": "REQUEST_TOO_LARGE",
            "status": 413,
            "type": "https://spiralistai.com/problems/request-too-large",
            "detail": "The request body exceeds the endpoint limit."
        },
        "DEPLOYMENT_MARKER_MISMATCH": {
            "code": "DEPLOYMENT_MARKER_MISMATCH",
            "status": 409,
            "type": "https://spiralistai.com/problems/deployment-marker-mismatch",
            "detail": "Advertised page and API deployment markers conflict."
        },
        "INTERNAL_GENERATION_FAILURE": {
            "code": "INTERNAL_GENERATION_FAILURE",
            "status": 500,
            "type": "https://spiralistai.com/problems/internal-generation-failure",
            "detail": "A persona could not be generated."
        }
    },
    "standards": [
        {
            "name": "HTTP Semantics",
            "reference": "RFC 9110",
            "usage": "Methods, status codes, conditional requests, and representation metadata."
        },
        {
            "name": "Problem Details for HTTP APIs",
            "reference": "RFC 9457",
            "usage": "Typed application/problem+json failures."
        },
        {
            "name": "Digest Fields",
            "reference": "RFC 9530",
            "usage": "Content-Digest response integrity."
        },
        {
            "name": "Web Linking",
            "reference": "RFC 8288",
            "usage": "Link relations for documentation, schemas, status, and OpenAPI."
        },
        {
            "name": "OpenAPI",
            "reference": "OpenAPI 3.1.0",
            "usage": "Machine-readable public API description."
        },
        {
            "name": "JSON Schema",
            "reference": "2020-12",
            "usage": "Request, response, prompt-separation, pagination, and problem schemas."
        },
        {
            "name": "Idempotency-Key",
            "reference": "IETF HTTPAPI draft",
            "usage": "Syntax validation and correlation only; durable replay is not claimed."
        },
        {
            "name": "UAIX persona boundary",
            "reference": "persona-only-runtime-overlay-excluded-v1",
            "usage": "Persona packages exclude the separately authored platform overlay."
        }
    ],
    "schemas": [
        {
            "path": "/api/schemas/problem-v2.schema.json",
            "url": "https://spiralistai.com/api/schemas/problem-v2.schema.json"
        },
        {
            "path": "/api/schemas/api-platform-contract.schema.json",
            "url": "https://spiralistai.com/api/schemas/api-platform-contract.schema.json"
        },
        {
            "path": "/api/schemas/pagination.schema.json",
            "url": "https://spiralistai.com/api/schemas/pagination.schema.json"
        },
        {
            "path": "/api/schemas/prompt-separation.schema.json",
            "url": "https://spiralistai.com/api/schemas/prompt-separation.schema.json"
        },
        {
            "path": "/api/schemas/admin-batch-persona.schema.json",
            "url": "https://spiralistai.com/api/schemas/admin-batch-persona.schema.json"
        }
    ],
    "links": {
        "contract": "https://spiralistai.com/api/v1/contract/",
        "endpoints": "https://spiralistai.com/api/v1/endpoints/",
        "examples": "https://spiralistai.com/api/v1/examples/",
        "problems": "https://spiralistai.com/api/v1/problems/",
        "headers": "https://spiralistai.com/api/v1/headers/",
        "standards": "https://spiralistai.com/api/v1/standards/",
        "schemas": "https://spiralistai.com/api/v1/schemas/",
        "changelog": "https://spiralistai.com/api/v1/changelog/",
        "openapiValidation": "https://spiralistai.com/api/v1/openapi/validation/",
        "guide": "https://spiralistai.com/api-guide/",
        "openapiJson": "https://spiralistai.com/openapi.json",
        "openapiYaml": "https://spiralistai.com/openapi.yaml",
        "publicUai": "https://spiralistai.com/uai/index.uai",
        "adminBatch": "https://spiralistai.com/api/v1/admin/batch-personas/",
        "adminPage": "https://spiralistai.com/admin/"
    },
    "limits": {
        "durableIdempotencyReplay": false,
        "exactlyOnceGeneration": false,
        "adminBrowserMayRepeatBoundedRequests": true,
        "hostPlatformSafetyCanBeRemoved": false,
        "personaUaixCanContainPlatformOverlay": false
    }
}