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

Routers Overview

• zyra.api.routers.cli

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

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

  • POST /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 /search — Perform discovery across sources (local/profile/OGC); JSON output

  • GET /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

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

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

• 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