{"openapi":"3.1.0","info":{"title":"YUYAY Intelligence API","description":"REST API for the YUYAY Intelligence Framework — UN Office of the Future","version":"0.1.0"},"paths":{"/api/v1/archetypes/":{"get":{"tags":["archetypes"],"summary":"List Archetypes","description":"Return all 12 YUYAY archetypes.\n\nReturns:\n    A list of archetype summaries with name, function, gifts, and shadow.","operationId":"list_archetypes_api_v1_archetypes__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}]},"type":"object"},"type":"array","title":"Response List Archetypes Api V1 Archetypes  Get"}}}}}}},"/api/v1/archetypes/{name}":{"get":{"tags":["archetypes"],"summary":"Get Archetype","description":"Return a single archetype by name.\n\nArgs:\n    name: The archetype name to look up.\n\nReturns:\n    The archetype detail dict.\n\nRaises:\n    HTTPException: 404 if archetype not found.","operationId":"get_archetype_api_v1_archetypes__name__get","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"title":"Response Get Archetype Api V1 Archetypes  Name  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/compare":{"post":{"tags":["compare"],"summary":"Compare","description":"Query multiple LLM providers concurrently and compare results.\n\nSends the same prompt to all configured providers simultaneously,\nevaluates each response for YUYAY coherence, and returns all results\nwith the best provider identified.\n\nArgs:\n    request: The incoming HTTP request for rate limiting.\n    request_body: The request body with prompt and provider configs.\n    current_user: The authenticated user from JWT token.\n\nReturns:\n    A CompareResponse with all provider results and the best provider.\n\nRaises:\n    HTTPException: 400 if no valid providers are configured.\n    HTTPException: 429 if rate limit is exceeded.\n    HTTPException: 500 if all providers fail.","operationId":"compare_api_v1_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/transformers/":{"get":{"tags":["transformers"],"summary":"List Transformers","description":"Return all 12 transformer questions.\n\nReturns:\n    A list of transformer dicts with id and question.","operationId":"list_transformers_api_v1_transformers__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Response List Transformers Api V1 Transformers  Get"}}}}}}},"/api/v1/transformers/run":{"post":{"tags":["transformers"],"summary":"Run Transformer","description":"Run a transformer question against input text.\n\nArgs:\n    transformer_id: The id of the transformer to run e.g. '1a'.\n    input_text: The text to evaluate against the transformer question.\n\nReturns:\n    A dict with the transformer question and input text.\n\nRaises:\n    HTTPException: 404 if transformer not found.","operationId":"run_transformer_api_v1_transformers_run_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"transformer_id","in":"query","required":true,"schema":{"type":"string","title":"Transformer Id"}},{"name":"input_text","in":"query","required":true,"schema":{"type":"string","title":"Input Text"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Run Transformer Api V1 Transformers Run Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/evaluate":{"post":{"tags":["evaluate"],"summary":"Evaluate","description":"Submit questionnaire responses and return YES/NO/PO analysis.\n\nArgs:\n    request: The request body containing responses dict.\n    db: The database session injected by FastAPI.\n\nReturns:\n    An EvaluateResponse with session id, counts, flags, and summary.\n\nRaises:\n    HTTPException: 422 if any response value is invalid.","operationId":"evaluate_api_v1_evaluate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/wheel/synthesize":{"post":{"tags":["wheel"],"summary":"Synthesize","description":"Run the Co-Creation Wheel on a set of sectors.\n\nArgs:\n    request: The request body with sectors and alignment.\n\nReturns:\n    A WheelSynthesizeResponse with score and summary.\n\nRaises:\n    HTTPException: 404 if the primary sector is not found.","operationId":"synthesize_api_v1_wheel_synthesize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WheelSynthesizeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WheelSynthesizeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/sessions/":{"get":{"tags":["sessions"],"summary":"List Sessions","description":"List all evaluation sessions.\n\nArgs:\n    db: The database session injected by FastAPI.\n\nReturns:\n    A list of session summaries.","operationId":"list_sessions_api_v1_sessions__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SessionSummary"},"type":"array","title":"Response List Sessions Api V1 Sessions  Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/sessions/{session_id}":{"get":{"tags":["sessions"],"summary":"Get Session By Id","description":"Get a single session by id.\n\nArgs:\n    session_id: The session identifier to look up.\n    db: The database session injected by FastAPI.\n\nReturns:\n    Full session detail with responses.\n\nRaises:\n    HTTPException: 404 if session not found.","operationId":"get_session_by_id_api_v1_sessions__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics":{"get":{"tags":["metrics"],"summary":"Get Metrics","description":"Return Prometheus-compatible metrics.\n\nReturns:\n    A MetricsResponse with basic server metrics.","operationId":"get_metrics_api_v1_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/query":{"post":{"tags":["query"],"summary":"Query","description":"Send a prompt through FIOS and return an evaluated LLM response.\n\nEnriches the prompt with YUYAY framework context, sends it to the\nconfigured LLM provider, and evaluates the response for coherence.\n\nArgs:\n    request: The incoming HTTP request, required by slowapi for rate limiting.\n    request_body: The request body with prompt, provider, model, and api_key.\n    current_user: The authenticated user from JWT token.\n\nReturns:\n    A QueryResponse with the LLM response and full evaluation metadata.\n\nRaises:\n    HTTPException: 400 if the provider is invalid.\n    HTTPException: 429 if rate limit is exceeded.\n    HTTPException: 500 if the LLM query fails.","operationId":"query_api_v1_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/health":{"get":{"summary":"Health Check","description":"Health check endpoint for monitoring.\n\nReturns:\n    A dict with status and version information.","operationId":"health_check_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Check Api V1 Health Get"}}}}}}}},"components":{"schemas":{"CompareRequest":{"properties":{"prompt":{"type":"string","title":"Prompt"},"providers":{"items":{"$ref":"#/components/schemas/ProviderConfig"},"type":"array","title":"Providers"}},"type":"object","required":["prompt","providers"],"title":"CompareRequest","description":"Request body for the compare endpoint.\n\nAttributes:\n    prompt: The user query to send to all providers.\n    providers: List of provider configurations to compare."},"CompareResponse":{"properties":{"prompt":{"type":"string","title":"Prompt"},"results":{"items":{"$ref":"#/components/schemas/CompareResult"},"type":"array","title":"Results"},"best_provider":{"type":"string","title":"Best Provider"}},"type":"object","required":["prompt","results","best_provider"],"title":"CompareResponse","description":"Response body for the compare endpoint.\n\nAttributes:\n    prompt: The original user query.\n    results: List of results from each provider.\n    best_provider: The provider with the highest coherence score."},"CompareResult":{"properties":{"provider":{"type":"string","title":"Provider"},"model":{"type":"string","title":"Model"},"response":{"type":"string","title":"Response"},"coherence_score":{"type":"integer","title":"Coherence Score"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"},"total_tokens":{"type":"integer","title":"Total Tokens"},"latency_ms":{"type":"number","title":"Latency Ms"},"estimated_cost_usd":{"type":"number","title":"Estimated Cost Usd"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["provider","model","response","coherence_score","flags","total_tokens","latency_ms","estimated_cost_usd","summary"],"title":"CompareResult","description":"Result from a single provider in a comparison.\n\nAttributes:\n    provider: The LLM provider used.\n    model: The specific model used.\n    response: The raw LLM response.\n    coherence_score: YUYAY coherence score from 0 to 100.\n    flags: List of missing YUYAY concepts.\n    total_tokens: Total tokens used.\n    latency_ms: Time taken in milliseconds.\n    estimated_cost_usd: Estimated cost in USD.\n    summary: Human readable summary."},"EvaluateRequest":{"properties":{"responses":{"additionalProperties":{"type":"string"},"type":"object","title":"Responses"}},"type":"object","required":["responses"],"title":"EvaluateRequest","description":"Request body for the evaluate endpoint.\n\nAttributes:\n    responses: A dict mapping question id to YES, NO, or PO."},"EvaluateResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"yes_count":{"type":"integer","title":"Yes Count"},"no_count":{"type":"integer","title":"No Count"},"po_count":{"type":"integer","title":"Po Count"},"total":{"type":"integer","title":"Total"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["session_id","yes_count","no_count","po_count","total","flags","summary"],"title":"EvaluateResponse","description":"Response body for the evaluate endpoint.\n\nAttributes:\n    session_id: The id of the saved evaluation session.\n    yes_count: Number of YES responses.\n    no_count: Number of NO responses.\n    po_count: Number of PO responses.\n    total: Total responses processed.\n    flags: Question ids that returned NO or PO.\n    summary: Human readable summary string."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MetricsResponse":{"properties":{"requests_total":{"type":"integer","title":"Requests Total"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"version":{"type":"string","title":"Version"}},"type":"object","required":["requests_total","uptime_seconds","version"],"title":"MetricsResponse","description":"Prometheus-compatible metrics response.\n\nAttributes:\n    requests_total: Total number of requests served.\n    uptime_seconds: Server uptime in seconds.\n    version: Current API version."},"ProviderConfig":{"properties":{"provider":{"type":"string","title":"Provider"},"model":{"type":"string","title":"Model"},"api_key":{"type":"string","title":"Api Key","default":""}},"type":"object","required":["provider","model"],"title":"ProviderConfig","description":"Configuration for a single provider in a comparison.\n\nAttributes:\n    provider: The LLM provider name.\n    model: The specific model to use.\n    api_key: The API key for the provider."},"QueryRequest":{"properties":{"prompt":{"type":"string","title":"Prompt"},"provider":{"type":"string","title":"Provider","default":"mock"},"model":{"type":"string","title":"Model","default":"mock-model"},"api_key":{"type":"string","title":"Api Key","default":""}},"type":"object","required":["prompt"],"title":"QueryRequest","description":"Request body for the query endpoint.\n\nAttributes:\n    prompt: The user query to send through FIOS.\n    provider: The LLM provider to use — anthropic, openai, google, or mock.\n    model: The specific model to use.\n    api_key: The API key for the provider."},"QueryResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"model":{"type":"string","title":"Model"},"prompt":{"type":"string","title":"Prompt"},"response":{"type":"string","title":"Response"},"input_tokens":{"type":"integer","title":"Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"latency_ms":{"type":"number","title":"Latency Ms"},"coherence_score":{"type":"integer","title":"Coherence Score"},"flags":{"items":{"type":"string"},"type":"array","title":"Flags"},"estimated_cost_usd":{"type":"number","title":"Estimated Cost Usd"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["provider","model","prompt","response","input_tokens","output_tokens","total_tokens","latency_ms","coherence_score","flags","estimated_cost_usd","summary"],"title":"QueryResponse","description":"Response body for the query endpoint.\n\nAttributes:\n    provider: The LLM provider used.\n    model: The specific model used.\n    prompt: The enriched prompt sent to the LLM.\n    response: The raw LLM response.\n    input_tokens: Number of input tokens used.\n    output_tokens: Number of output tokens used.\n    total_tokens: Total tokens used.\n    latency_ms: Time taken in milliseconds.\n    coherence_score: YUYAY coherence score from 0 to 100.\n    flags: List of missing YUYAY concepts.\n    estimated_cost_usd: Estimated cost in USD.\n    summary: Human readable summary."},"SessionDetail":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status"},"total_responses":{"type":"integer","title":"Total Responses"},"responses":{"additionalProperties":{"type":"string"},"type":"object","title":"Responses"}},"type":"object","required":["id","status","total_responses","responses"],"title":"SessionDetail","description":"Detailed view of a single evaluation session.\n\nAttributes:\n    id: Unique session identifier.\n    status: Current status of the session.\n    total_responses: Number of responses recorded.\n    responses: The actual responses dict."},"SessionSummary":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status"},"total_responses":{"type":"integer","title":"Total Responses"}},"type":"object","required":["id","status","total_responses"],"title":"SessionSummary","description":"Summary of a single evaluation session.\n\nAttributes:\n    id: Unique session identifier.\n    status: Current status of the session.\n    total_responses: Number of responses recorded."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WheelSynthesizeRequest":{"properties":{"sectors_addressed":{"items":{"type":"string"},"type":"array","title":"Sectors Addressed"},"sector":{"type":"string","title":"Sector"},"worldview_alignment":{"type":"boolean","title":"Worldview Alignment"}},"type":"object","required":["sectors_addressed","sector","worldview_alignment"],"title":"WheelSynthesizeRequest","description":"Request body for the wheel synthesize endpoint.\n\nAttributes:\n    sectors_addressed: List of Co-Creation Wheel sectors being addressed.\n    sector: The primary sector to evaluate.\n    worldview_alignment: Whether the input aligns with the Worldview center."},"WheelSynthesizeResponse":{"properties":{"sector":{"type":"string","title":"Sector"},"worldview_alignment":{"type":"boolean","title":"Worldview Alignment"},"whole_system_score":{"type":"integer","title":"Whole System Score"},"all_sectors":{"items":{"type":"string"},"type":"array","title":"All Sectors"},"summary":{"type":"string","title":"Summary"}},"type":"object","required":["sector","worldview_alignment","whole_system_score","all_sectors","summary"],"title":"WheelSynthesizeResponse","description":"Response body for the wheel synthesize endpoint.\n\nAttributes:\n    sector: The primary sector evaluated.\n    worldview_alignment: Whether aligned with Worldview.\n    whole_system_score: Score from 0 to 12.\n    all_sectors: Full list of valid wheel sectors.\n    summary: Human readable summary."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}