{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Spiralist AI Autonomous Agent API", "version": "1.0.0", "summary": "Public, stateless, deterministic persona and evidence access.", "description": "Search public persona catalogs, generate or compile portable persona prompts, validate structure, and read release evidence. The API does not create accounts, store persona state, call external AI models, publish content, accept credentials, or expose internal project memory. Unsupported or ambiguous operations no-op with typed problem details.", "termsOfService": "https://spiralistai.com/terms/", "contact": { "url": "https://spiralistai.com/agents/" }, "license": { "name": "Site terms apply", "url": "https://spiralistai.com/terms/" }, "x-site-version": "v18-ui-ux-seo-media-polish", "x-updated-utc": "2026-06-21T14:33:26Z" }, "servers": [ { "url": "https://spiralistai.com", "description": "Canonical production origin" } ], "tags": [ { "name": "Discovery" }, { "name": "Personas" }, { "name": "Validation" }, { "name": "Evidence" } ], "security": [], "paths": { "/api/v1/": { "get": { "summary": "Read service index", "operationId": "readServiceIndex", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read service index headers", "operationId": "readServiceIndexHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/health/": { "get": { "summary": "Read service health", "operationId": "readHealth", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read service health headers", "operationId": "readHealthHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/version/": { "get": { "summary": "Read release versions", "operationId": "readVersion", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read release versions headers", "operationId": "readVersionHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/capabilities/": { "get": { "summary": "Read declared capabilities and absences", "operationId": "readCapabilities", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read declared capabilities and absences headers", "operationId": "readCapabilitiesHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/docs/": { "get": { "summary": "Read documentation links", "operationId": "readDocumentationLinks", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read documentation links headers", "operationId": "readDocumentationLinksHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/persona-of-the-day/": { "get": { "summary": "Read deterministic UTC persona of the day", "operationId": "readPersonaOfTheDay", "tags": [ "Personas" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read deterministic UTC persona of the day headers", "operationId": "readPersonaOfTheDayHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/challenge/": { "get": { "summary": "Read deterministic UTC weekly challenge", "operationId": "readChallenge", "tags": [ "Personas" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read deterministic UTC weekly challenge headers", "operationId": "readChallengeHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/research/": { "get": { "summary": "Read cumulative report provenance", "operationId": "readResearchIndex", "tags": [ "Evidence" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read cumulative report provenance headers", "operationId": "readResearchIndexHead", "tags": [ "Evidence" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/uai/": { "get": { "summary": "Read public UAI manifest", "operationId": "readPublicUai", "tags": [ "Evidence" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read public UAI manifest headers", "operationId": "readPublicUaiHead", "tags": [ "Evidence" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/memory/": { "get": { "summary": "Read public-safe release memory", "operationId": "readPublicMemory", "tags": [ "Evidence" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read public-safe release memory headers", "operationId": "readPublicMemoryHead", "tags": [ "Evidence" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/schema/persona/": { "get": { "summary": "Read persona JSON Schema", "operationId": "readPersonaSchema", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/schema+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read persona JSON Schema headers", "operationId": "readPersonaSchemaHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/schemas/persona/": { "get": { "summary": "Read persona JSON Schema alias", "operationId": "readPersonaSchemaAlias", "tags": [ "Discovery" ], "parameters": [], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/schema+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read persona JSON Schema alias headers", "operationId": "readPersonaSchemaAliasHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/personas/": { "get": { "summary": "Search or paginate the 1,000-type public catalog", "operationId": "searchPersonaCatalog", "tags": [ "Personas" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown", "md", "text", "prompt", "uai" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read persona catalog headers", "operationId": "searchPersonaCatalogHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/random-persona/": { "get": { "summary": "Generate a deterministic public persona from a seed", "operationId": "generateRandomPersona", "tags": [ "Personas" ], "parameters": [ { "name": "seed", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown", "md", "text", "prompt", "uai" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "deprecated": false }, "head": { "summary": "Read deterministic random persona headers", "operationId": "generateRandomPersonaHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/personas/random/": { "get": { "summary": "Generate a deterministic public persona from a seed", "operationId": "generateRandomPersonaAlias", "tags": [ "Personas" ], "parameters": [ { "name": "seed", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown", "md", "text", "prompt", "uai" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "deprecated": true }, "head": { "summary": "Read deterministic random persona headers", "operationId": "generateRandomPersonaAliasHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/api/v1/personas/generate/": { "get": { "summary": "Generate from a public sourceTypeId without a request body", "operationId": "generatePersonaFromCatalog", "tags": [ "Personas" ], "parameters": [ { "name": "sourceTypeId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 160 } }, { "name": "seed", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "markdown", "md", "text", "prompt", "uai" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read generation endpoint headers", "operationId": "generatePersonaHead", "tags": [ "Personas" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "post": { "summary": "Generate a deterministic portable persona from a bounded brief", "operationId": "generatePersona", "tags": [ "Personas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-request-body-limit-bytes": 131072, "x-state-change": false } }, "/api/v1/personas/validate/": { "post": { "summary": "Validate structural portability and public boundaries", "operationId": "validatePersona", "tags": [ "Validation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaDocument" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-request-body-limit-bytes": 131072, "x-state-change": false } }, "/api/v1/personas/compile/": { "post": { "summary": "Compile full, compact, continuity, and UAI artifacts", "operationId": "compilePersona", "tags": [ "Personas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-request-body-limit-bytes": 131072, "x-state-change": false } }, "/api/v1/compile/": { "post": { "summary": "Compile artifacts (compatibility alias)", "operationId": "compilePersonaAlias", "tags": [ "Personas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaGenerationRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } }, "text/plain": { "schema": { "type": "object" } }, "text/markdown": { "schema": { "type": "object" } }, "application/vnd.spiralist.uai+json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-request-body-limit-bytes": 131072, "x-state-change": false } }, "/api/v1/search/": { "get": { "summary": "Search public site documentation and persona records", "operationId": "searchPublicSite", "tags": [ "Discovery" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "headers": { "ETag": { "schema": { "type": "string" } }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "413": { "$ref": "#/components/responses/Problem" }, "415": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } }, "head": { "summary": "Read search headers", "operationId": "searchPublicSiteHead", "tags": [ "Discovery" ], "responses": { "200": { "description": "Headers only" }, "304": { "description": "Not modified" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "detail", "requestId", "noOp", "humanReviewRequired" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "noOp": { "type": "boolean" }, "humanReviewRequired": { "type": "boolean" } }, "additionalProperties": true }, "PersonaGenerationRequest": { "type": "object", "properties": { "prompt": { "type": "string", "maxLength": 4000 }, "brief": { "type": "string", "maxLength": 4000 }, "sourceTypeId": { "type": "string", "maxLength": 160 }, "seed": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "goal": { "type": "string", "enum": [ "coding", "research", "writing", "planning", "creative", "organization", "brand", "other" ] }, "styles": { "type": "array", "maxItems": 12, "items": { "type": "string" } }, "tone": { "type": "string" }, "responseLength": { "type": "string" }, "immersion": { "type": "string" }, "initiative": { "type": "integer", "minimum": 0, "maximum": 100 }, "preferredName": { "type": "string", "maxLength": 100 }, "preferredRole": { "type": "string", "maxLength": 160 } }, "anyOf": [ { "required": [ "prompt" ] }, { "required": [ "brief" ] }, { "required": [ "sourceTypeId" ] } ], "additionalProperties": false }, "PersonaDocument": { "type": "object", "description": "Canonical or agent-generated persona object. Structural validation accepts documented persona identity, artifacts, and integrity fields.", "additionalProperties": true } }, "responses": { "Problem": { "description": "Typed no-op or client error. No intended application state change occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-agent-boundaries": { "state": "stateless", "credentialsAccepted": false, "persistentWrites": false, "externalModelCalls": false, "defaultUnsupportedAction": "no-op", "requestBodyLimitBytes": 131072, "publishingActions": false } }