## Authentication

New Pixcode API keys start with `px_`. Older `ck_` keys remain accepted for compatibility, but new documentation and examples should use `px_`.

    curl http://localhost:3001/api/projects \
      -H "Authorization: Bearer px_your_key_here"

    curl http://localhost:3001/api/projects \
      -H "X-API-Key: px_your_key_here"

## Run a one-shot agent task

`POST /api/agent` is the external REST entry point for non-interactive automation. It can run a provider against a project path, optionally stream events, and optionally return buffered JSON with `stream: false`.

    curl http://localhost:3001/api/agent \
      -H "Authorization: Bearer px_your_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "provider": "codex",
        "projectPath": "/home/me/project",
        "message": "Review the current diff and list release risks.",
        "stream": false
      }'

## Workflow automation

Orchestration endpoints can list workflow modes, preview expanded DAGs, start runs, read run state, stream events, and cancel active work.

Preview

Validate agent metadata and inspect the node graph before running child agents.

Run

Start the workflow and track node runs, Hermes task IDs, status, events, and output.

Stream

Use run event endpoints to follow progress in dashboards or CLI scripts.

Cancel

Stop active orchestration runs when the user changes direction or detects bad output.

## Common integration ideas

- Ask Codex or Claude Code to review a Git diff from a CI job before release.
- Trigger OpenCode or Gemini CLI from a custom internal dashboard.
- Build a Telegram command that starts a Pixcode agent run on an always-on server.
- Run multi-agent review on a branch before creating a tag or npm publish.
- Expose a safe internal tool that lists projects and starts approved workflows.

Full OpenAPI reference: openapi.yaml.