# AgentRail

## Docs

- [POST /agent-api-keys — create an agent API key](https://agentrail.app/docs/api/auth/create-key.md): Issue a scoped bearer key for one agent identity. The secret is returned only once — store it immediately in your runtime or secret manager.
- [AgentRail API key scopes and permissions reference](https://agentrail.app/docs/api/auth/scopes.md): Complete reference for all AgentRail agent key permission scopes, with guidance on least-privilege scope sets for common agent roles.
- [GET /task-events/stream — SSE task event stream](https://agentrail.app/docs/api/events/stream.md): Open a long-lived Server-Sent Events connection to receive real-time task lifecycle events, with cursor-based replay for missed events on reconnect.
- [GET /tasks/:id/ci-status — read CI check results](https://agentrail.app/docs/api/tasks/ci-status.md): Read the aggregated CI status for a task's latest submission, including per-workflow and per-check results, failure summaries, and flaky hints.
- [GET /tasks/:id — get full task details and state](https://agentrail.app/docs/api/tasks/get.md): Retrieve the full detail record for one task, including lifecycle status, source metadata, PR state, routing context, and availableActions.
- [GET /tasks/mine — list all your assigned tasks](https://agentrail.app/docs/api/tasks/list.md): Fetch the compact list of tasks currently assigned to your agent, with optional status filtering, pagination, and per-task availableActions.
- [GET /tasks/:id/review-feedback — read PR reviews](https://agentrail.app/docs/api/tasks/review-feedback.md): Retrieve the latest reviewer decision and inline comments for a task's pull request, including the outcome, head SHA, and per-comment severity.
- [POST /tasks/:id/ship — merge and deploy a task](https://agentrail.app/docs/api/tasks/ship.md): Trigger a merge-and-deploy operation for an approved task. Requires CI to be green, review to be approved, and the correct head commit SHA.
- [POST /tasks/:id/submit — submit completed work](https://agentrail.app/docs/api/tasks/submit.md): Submit finished work for review. AgentRail creates or reuses the provider PR and returns the PR URL, number, and review routing details.
- [POST /event-subscriptions — manage webhook delivery](https://agentrail.app/docs/api/webhooks/subscriptions.md): Create, list, and deactivate durable webhook subscriptions. AgentRail signs every delivery with HMAC-SHA256 for secure verification.
- [Providers: Connect GitHub, CircleCI, and Linear to AgentRail](https://agentrail.app/docs/concepts/providers.md): Use agentrail provider connect to wire up GitHub for PRs and review, CircleCI for CI status, and Linear for issue import with readiness verification.
- [Routing: How AgentRail Assigns Issues to the Right Agent](https://agentrail.app/docs/concepts/routing.md): AgentRail evaluates routing rules to assign incoming issues deterministically or with AI assistance, and records every assignment in a local audit store.
- [Task Lifecycle: From Provider Issue to Shipped Code](https://agentrail.app/docs/concepts/task-lifecycle.md): How AgentRail moves a task from intake through routing, agent work, CI, and review to ship — and how the availableActions field guides each step.
- [Authenticate your coding agents with AgentRail keys](https://agentrail.app/docs/configuration/auth.md): Get your AgentRail API key, load it into your agent environment, understand key scopes, and resolve common 401 and 403 auth errors.
- [Configure AgentRail routing, providers, and run policy](https://agentrail.app/docs/configuration/overview.md): Learn how to view and update your AgentRail config, manage repos, choose provider and routing modes, and tune managed run reclaim defaults.
- [Check and control AgentRail's anonymous usage telemetry](https://agentrail.app/docs/configuration/telemetry.md): Understand what anonymous telemetry AgentRail collects, what it never sends, and how to check or change your telemetry preference at any time.
- [Installation: CLI, Docker, and SDK Setup for AgentRail](https://agentrail.app/docs/installation.md): Install the AgentRail CLI with npm or npx, run the server with Docker, and configure GitHub, CircleCI, and Linear tokens via environment variables.
- [Connect your CircleCI pipelines and projects to AgentRail](https://agentrail.app/docs/integrations/circleci.md): Link CircleCI to AgentRail to track pipeline status for agent branches. Covers project slug, config file creation, webhook verification, and health checks.
- [Use AgentRail with Claude Code as your coding agent](https://agentrail.app/docs/integrations/claude-code.md): Run Claude Code as a managed AgentRail agent or trigger single debug runs. Covers environment variables, run-scoped commands, and handoff reporting.
- [Use AgentRail with OpenAI Codex as your coding agent](https://agentrail.app/docs/integrations/codex.md): Run Codex as a managed AgentRail agent or trigger single debug runs. Covers environment setup, run-scoped commands, and progress and completion reporting.
- [Use AgentRail with Cursor as your AI coding editor](https://agentrail.app/docs/integrations/cursor.md): Open Cursor from an AgentRail worktree and add a Cursor rule so it stays focused on repository work without calling AgentRail lifecycle endpoints.
- [Connect your GitHub account and repos to AgentRail](https://agentrail.app/docs/integrations/github.md): Link GitHub to AgentRail for PR submission, GitHub Actions CI status, and review observation. Covers review policy options and health check commands.
- [Connect your Linear workspace and issues to AgentRail](https://agentrail.app/docs/integrations/linear.md): Link Linear to AgentRail to import issues and route them to the right agent. Covers connection setup, import by identifier or URL, and routing behavior.
- [AgentRail: A Lifecycle Control Plane for Coding Agents](https://agentrail.app/docs/introduction.md): AgentRail gives coding agents a single API for issue intake, routing, CI, review, and ship — no polling, compact task state, and retry-safe mutations.
- [Quickstart: Get AgentRail Running in Under Five Minutes](https://agentrail.app/docs/quickstart.md): Install the CLI, run agentrail init, start the local API, create your first agent, and confirm setup with agentrail doctor — all in five minutes.
- [Authenticate your AgentRail SDK client with API keys](https://agentrail.app/docs/sdk/authentication.md): Configure AGENTRAIL_BASE_URL and AGENTRAIL_API_KEY, understand bearer tokens vs key IDs, assign scopes, and resolve 401 and 403 errors.
- [AgentRail SDK overview: harnesses, MCP, and runners](https://agentrail.app/docs/sdk/overview.md): Learn when to use the TypeScript or Python SDK to build agent harnesses, MCP servers, and workflow runners, and when to use the CLI instead.
- [AgentRailClient task lifecycle methods — Python SDK](https://agentrail.app/docs/sdk/python/client.md): Use the Python AgentRailClient to list tasks, submit work, read CI and review status, and ship completed tasks through the full lifecycle.
- [Stream AgentRail task lifecycle events — Python SDK](https://agentrail.app/docs/sdk/python/events.md): Use client.stream_events with StreamOptions to receive real-time task lifecycle events as Pydantic models, with cursor-based reconnection.
- [Install and configure the AgentRail Python SDK client](https://agentrail.app/docs/sdk/python/installation.md): Add the agentrail package to your Python 3.10+ project, install from the local repo for pre-release work, and use the async context manager.
- [Verify incoming AgentRail webhook events in Python](https://agentrail.app/docs/sdk/python/webhooks.md): Use parse_webhook_event from the agentrail package to verify the HMAC signature on webhook deliveries before processing the event data.
- [AgentRailClient task lifecycle methods — TypeScript SDK](https://agentrail.app/docs/sdk/typescript/client.md): Use the TypeScript AgentRailClient to list tasks, submit work, read CI and review status, and ship completed tasks with typed method signatures.
- [Stream AgentRail task events with the TypeScript SDK](https://agentrail.app/docs/sdk/typescript/events.md): Use client.streamEvents to receive real-time task lifecycle events over SSE, with AbortController cancellation and cursor-based reconnection.
- [Install and configure the AgentRail TypeScript SDK](https://agentrail.app/docs/sdk/typescript/installation.md): Add @agentrail-core/sdk to your Node.js 18+ project, install from the local repo for pre-release work, and import client and error classes.
- [Verify incoming AgentRail webhook events in TypeScript](https://agentrail.app/docs/sdk/typescript/webhooks.md): Use parseWebhookEvent from @agentrail-core/sdk to verify the HMAC signature on webhook deliveries before processing the event data.
- [Start the AgentRail API server with Docker Compose](https://agentrail.app/docs/self-hosting/docker.md): Start the AgentRail API server in a Docker container, then complete setup with the CLI to create agents, configure routing, and verify with doctor.
- [Self-host AgentRail on your local hardware or a VPS](https://agentrail.app/docs/self-hosting/overview.md): Run AgentRail on your own hardware or a VPS. Understand what self-hosting includes, what it doesn't, and which setup path to follow.