Domain APIs (v1)

Zyra exposes high-level, domain-oriented endpoints that delegate to the underlying CLI via /v1/cli/run. These endpoints provide clearer grouping by intent while retaining full CLI capability.

Endpoints

• POST /v1/process — Orchestration and data processing

• POST /v1/visualize — Static images, animations, plots

• POST /v1/disseminate — Export/egress (local path, S3, HTTP POST, etc.)

• POST /v1/export — Alias of /v1/disseminate (preferred)

• POST /v1/decimate — Legacy alias (deprecated; still supported)

• POST /v1/assets — Convenience alias for asset I/O (maps to decimate or acquire)

Request/Response Shape

Request body:

{
  "tool": "<command>",
  "args": { /* key/value pairs */ },
  "options": { "mode": "sync" | "async", "timeout_ms": 60000, "dry_run": false }
}

Response (sync):

{
  "status": "ok" | "error",
  "result"?: { "argv"?: ["zyra", "<stage>", "<tool>", ...] },
  "logs"?: [ {"stream": "stdout"|"stderr"|"progress", "text": "..."} ],
  "stdout"?: "...",
  "stderr"?: "...",
  "exit_code"?: 0,
  "error"?: { "type": "execution_error", "message": "...", "details"?: { "exit_code": 1 } }
}

Response (async):

{
  "status": "accepted",
  "job_id": "...",
  "poll": "/v1/jobs/{id}",
  "download": "/v1/jobs/{id}/download",
  "manifest": "/v1/jobs/{id}/manifest"
}

Auth

If an API key is configured (ZYRA_API_KEY), include X-API-Key with each request (or set API_KEY_HEADER to customize the header name).

Examples

Process: convert format (stdout):

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \\
  -d '{
        "tool": "convert-format",
        "args": { "file_or_url": "https://example.com/sample.grib2", "format": "netcdf", "stdout": true },
        "options": { "mode": "sync" }
      }' \\
  http://localhost:8000/v1/process

Visualize: heatmap to PNG:

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \\
  -d '{
        "tool": "heatmap",
        "args": { "input": "samples/demo.npy", "output": "/tmp/heatmap.png", "width": 800, "height": 400 },
        "options": { "mode": "sync" }
      }' \\
  http://localhost:8000/v1/visualize

Visualize: contour to PNG (validation error example):

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \
  -d '{ "tool": "contour", "args": { } }' \
  http://localhost:8000/v1/visualize

# → HTTP 400
#   { "status": "error", "error": { "type": "validation_error", "message": "Invalid arguments", "details": { ... } } }

Disseminate: write to local:

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \\
  -d '{
        "tool": "local",
        "args": { "input": "-", "output": "/tmp/out.bin" },
        "options": { "mode": "sync" }
      }' \\
  http://localhost:8000/v1/disseminate --data-binary @file.bin

Assets: convenience alias:

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \\
  -d '{
        "tool": "s3",
        "args": { "input": "samples/demo.nc", "url": "s3://bucket/path/demo.nc" },
        "options": { "mode": "sync" }
      }' \\
  http://localhost:8000/v1/assets

Notes

• The tool must be a valid command within the target domain; otherwise a 400 error is returned with the list of allowed commands.

• /assets tries to route tools to decimate first, then to acquire if the tool exists there. This keeps simple asset I/O calls under one path.

Error model

• Standardized error object: {"type", "message", "details?", "retriable?"}

• Validation failures return HTTP 400 with error.type = "validation_error".

• Sync execution failures return HTTP 200 with status: "error" and error.type = "execution_error" (exit code included in details).

Visualize: animate frames (MP4 optional):

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \
  -d '{
        "tool": "animate",
        "args": { "input": "samples/demo.npy", "output_dir": "/tmp/frames", "fps": 24, "to_video": "/tmp/out.mp4" },
        "options": { "sync": true }
      }' \
  http://localhost:8000/v1/visualize

Disseminate: HTTP POST bytes:

curl -sS -H 'Content-Type: application/json' -H "X-API-Key: $ZYRA_API_KEY" \
  -d '{
        "tool": "post",
        "args": { "input": "/path/to/file.bin", "url": "https://example.com/ingest", "content_type": "application/octet-stream" },
        "options": { "sync": true }
      }' \
  http://localhost:8000/v1/disseminate