This page maps the FastAPI routers to their endpoints, with brief descriptions and auth notes.

Routers Overview

• zyra.api.routers.cli

  • GET /v1/cli/commands — Discovery: stages, commands, and argument schemas (with examples)

  • GET /v1/cli/examples — Curated example request bodies and pipelines

  • POST /v1/cli/run — Execute a CLI command (sync or async)

  • GET /examples — Interactive examples page (Upload → Run → Download, WS streaming)

  • Auth: Requires API key header when ZYRA_API_KEY is set (except /docs and /redoc)

• zyra.api.routers.search

  • GET /v1/search — Perform discovery across sources (local/profile/OGC); JSON output

  • GET /v1/search/profiles — List bundled discovery profiles

  • POST /search — Discovery with JSON body; set analyze: true for LLM-assisted summary and picks

  • Auth: Requires API key header when enabled

• zyra.api.routers.files

  • POST /upload — Multipart file upload; returns {file_id, path}

  • Auth: Requires API key header when enabled

  • Notes: Uploaded files are written under ZYRA_UPLOAD_DIR (default /tmp/zyra_uploads)

• zyra.api.routers.jobs

  • GET /jobs/{job_id} — Job status (stdout, stderr, exit_code, output_file, resolved_input_paths)

  • DELETE /jobs/{job_id} — Cancel a queued job

  • GET /jobs/{job_id}/manifest — JSON list of job artifacts (name, path, size, mtime, media_type)

  • GET /jobs/{job_id}/download — Download an artifact; supports ?file=NAME and ?zip=1

  • Auth: Requires API key header when enabled

  • Notes: Results under ZYRA_RESULTS_DIR/{job_id}; TTL via ZYRA_RESULTS_TTL_SECONDS; periodic prune via cleanup loop

• zyra.api.routers.ws

  • WS /ws/jobs/{job_id} — Live JSON messages for logs/progress/final payload

  • Query params:

    • api_key (when ZYRA_API_KEY is set) — required

    • stream=stdout,stderr,progress — filter which keys to stream

  • Auth: Fail-fast on bad/missing key (closes with code 1008, no data)

  • Modes: Redis pub/sub or in-memory pub/sub parity

• zyra.api.routers.mcp

  • GET /v1/mcp (and OPTIONS /v1/mcp) — MCP discovery payload for MCP clients

  • POST /v1/mcp — JSON-RPC 2.0 endpoint with methods:

    • initialize, statusReport (alias: status/report)

    • tools/list, tools/call (aliases: listTools, callTool)

  • GET /v1/mcp/progress/{job_id} — Server-Sent Events (SSE) stream for async job progress

  • WS /v1/ws/mcp — JSON-RPC frames over WebSocket (progress notifications on the same socket)

  • Auth: Header when enabled (HTTP); ?api_key= query param for WS when enabled

  • Notes: Body size limit via MCP_MAX_BODY_BYTES (bytes). See also /ws/jobs/{job_id} for job streaming.

• Domain routers (minimal domain APIs mapping to CLI):

  • zyra.api.routers.domain_process — POST /v1/process

  • zyra.api.routers.domain_visualize — POST /v1/visualize (alias: /v1/render)

  • zyra.api.routers.domain_assets — POST /v1/assets

  • zyra.api.routers.domain_disseminate — POST /v1/export (aliases: /v1/disseminate, legacy: /v1/decimate)

  • zyra.api.routers.domain_acquire — POST /v1/import (alias: /v1/acquire)

  • zyra.api.routers.domain_decide — POST /v1/decide (alias: /v1/optimize)

  • zyra.api.routers.domain_simulate — POST /v1/simulate

  • zyra.api.routers.domain_narrate — POST /v1/narrate

  • zyra.api.routers.domain_verify — POST /v1/verify

  • zyra.api.routers.domain_transform — POST /v1/transform

  • Behavior: Validates a domain-specific body (discriminator tool), normalizes args using CLI schemas, then delegates to /cli/run (sync or async). Async returns { status: 'accepted', job_id, poll, download, manifest }. Errors return a standardized validation_error or execution_error envelope instead of 422.

  • Limits & logging: Optional DOMAIN_MAX_BODY_BYTES limit; structured domain call logs are emitted with timings.

Auth Recap

• HTTP endpoints (CLI, Files, Jobs) require the API key header when configured

• WebSocket requires ?api_key= in the URL when configured

• /examples page can be gated with ZYRA_REQUIRE_KEY_FOR_EXAMPLES=1

• OpenAPI docs remain readable without a key

System & LLM

• GET /v1/health — service probe

• GET /v1/ready — readiness, includes checks (uploads path, disk, queue, binaries, llm)

• GET /v1/llm/test — optional LLM connectivity probe (provider/model resolved from env)

Common Workflows

• Upload → Run → Download

  1. POST /upload (store file_id)

  2. POST /cli/run (use file_id:<id> placeholder in args) — async returns job_id

  3. Stream: ws://.../ws/jobs/{job_id}?api_key=<key>&stream=progress

  4. GET /jobs/{job_id} until status=succeeded; GET /jobs/{job_id}/download to fetch artifact

• Discovery and Examples

  • GET /cli/commands for per-command schemas and examples

  • GET /cli/examples for curated examples; try them in /examples

Tags in OpenAPI

• cli — CLI discovery and execution

• files — Uploads

• jobs — Job status/manifest/download

• ws — WebSocket streaming

• mcp — MCP JSON-RPC and progress

• Domain tags — process, visualize, assets, export (aliases: disseminate, legacy: decimate), import (alias: acquire), decide (alias: optimize), simulate, narrate, verify, transform

• system — GET /health, GET /ready

Environment Variables (selected)

• Auth: ZYRA_API_KEY, ZYRA_API_KEY_HEADER, ZYRA_REQUIRE_KEY_FOR_EXAMPLES

• CORS: ZYRA_CORS_ALLOW_ALL, ZYRA_CORS_ORIGINS

• Uploads: ZYRA_UPLOAD_DIR

• Results: ZYRA_RESULTS_DIR, ZYRA_RESULTS_TTL_SECONDS, ZYRA_RESULTS_CLEAN_INTERVAL_SECONDS

• Streaming: ZYRA_USE_REDIS, ZYRA_REDIS_URL, ZYRA_QUEUE

• MCP: ENABLE_MCP (1/0), MCP_MAX_BODY_BYTES

• Domain: DOMAIN_MAX_BODY_BYTES

• Root/path behind proxies: API_ROOT_PATH (e.g., /zyra) — sets FastAPI root_path; server uses root_path_in_servers=True so OpenAPI and links include the prefix when mounted under a reverse proxy.

Behind a Proxy (tip)

• Set API_ROOT_PATH to the mount path (for example, /zyra).

• Ensure the proxy forwards standard headers (Host, X-Forwarded-Proto).

Example (nginx):

# .env for Zyra API
API_ROOT_PATH=/zyra

# nginx
location /zyra/ {
  proxy_pass         http://127.0.0.1:8000/;  # note trailing slash
  proxy_set_header   Host $host;
  proxy_set_header   X-Forwarded-Proto $scheme;
  proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
}

Notes

• The server renders links and OpenAPI under the configured root path.

• CORS can be enabled via CORS_ALLOW_ALL=1 or CORS_ORIGINS.