---
title: Admin API
description: HTTP admin API for managing Dispatch jobs, workflows, crons, and the DLQ.
---

The `api` package provides a Forge-style RESTful HTTP API for managing all Dispatch entities. Routes are prefixed at `/v1` by default.

## Setup

```go
import "github.com/xraph/dispatch/api"

mux := http.NewServeMux()
api.RegisterRoutes(mux, eng)

log.Fatal(http.ListenAndServe(":8080", mux))
```

When using the Forge extension, routes are registered automatically under the configured `BasePath` (default: `/api/dispatch`).

## Routes

### Jobs

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/jobs` | List jobs |
| `GET` | `/v1/jobs/:jobId` | Get job by ID |
| `POST` | `/v1/jobs/:jobId/cancel` | Cancel a pending job |
| `GET` | `/v1/jobs/counts` | Job counts by state |

### Workflows

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/workflows` | List workflow definitions |
| `GET` | `/v1/workflows/runs` | List workflow runs |
| `GET` | `/v1/workflows/runs/:runId` | Get a workflow run |

### Crons

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/crons` | List cron entries |
| `GET` | `/v1/crons/:cronId` | Get cron entry |
| `POST` | `/v1/crons/:cronId/enable` | Enable a cron entry |
| `POST` | `/v1/crons/:cronId/disable` | Disable a cron entry |
| `DELETE` | `/v1/crons/:cronId` | Delete a cron entry |

### DLQ

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/dlq` | List DLQ entries |
| `GET` | `/v1/dlq/:entryId` | Get a DLQ entry |
| `POST` | `/v1/dlq/:entryId/replay` | Replay a single entry |
| `POST` | `/v1/dlq/purge` | Purge all DLQ entries |
| `GET` | `/v1/dlq/count` | DLQ entry count |

### Stats

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/stats` | System-wide statistics |

## Error responses

All errors return JSON:

```json
{"error": "job not found"}
```