The @sizls/pluck-api package ships a Hono-based REST API that wraps @sizls/pluck. Every route is typed, auth-protected (dual-mode: API key or JWT), policy-gated on mutations, and audit-logged.

When to use the API vs the CLI vs MCP

CLI – local scripts and one-off work. Lowest setup cost.
MCP – agents calling Pluck through Claude Desktop / Cursor / Continue. Stdio transport.
REST API – remote callers, hosted usage, languages other than TypeScript. Bearer-token auth, rate-limited, JSON in/out.

All three share the same @sizls/pluck runtime. Behaviour is identical; the transport differs.

Base URL + authentication

Hosted

https://api.pluck.run

Every /v1/* route requires one of:

Authorization: Bearer <api-key>          # API keys, programmatic
Authorization: Bearer <jwt>              # JWT, dashboard sessions

Public unauthenticated routes: /health, /v1/auth/*.

Self-hosted

Run the server locally:

Shell

npx @sizls/pluck-api serve --port 8787
# or, from source:
pnpm --filter @sizls/pluck-api dev

Route reference

Every route is versioned under /v1/.

Health

Method	Path	Description
`GET`	`/health`	Liveness + uptime + version. No auth.

Response:

JSON

{ "status": "ok", "uptime": 1234.56, "version": "0.1.0" }

Pipeline phases

Wrappers around the core pipeline. Each returns a PluckResult serialised to JSON.

Method	Path	Body	Description
`POST`	`/v1/extract`	`{ uri, format?, mode? }`	Run the full connect → navigate → extract pipeline.
`POST`	`/v1/act`	`{ uri, action, input?, dryRun?, idempotencyKey?, confirm? }`	Run an action. Default `dryRun: true` – callers must pass `dryRun: false` to execute.
`POST`	`/v1/sense`	`{ uri, detect?, resolution? }`	Run the sense phase on an audio/video URI.
`POST`	`/v1/snitch`	`{ url, signed? }`	Privacy audit. When `signed: true` and a signing key is configured, the report is Ed25519-signed.

Monitors (drift detection)

Persistent URL watchers – poll on a schedule, emit an event on change, optionally fire a webhook.

Method	Path	Body	Description
`GET`	`/v1/monitors`	–	List the caller's monitors.
`POST`	`/v1/monitors`	`{ uri, checkInterval?, baselineHash?, webhookUrl? }`	Create a monitor.
`GET`	`/v1/monitors/:id`	–	Fetch a monitor.
`GET`	`/v1/monitors/:id/diffs`	–	Drift history – every check that detected a change.
`POST`	`/v1/monitors/:id/baseline`	–	Reset the baseline hash to the current content.
`PATCH`	`/v1/monitors/:id`	Partial monitor	Update a monitor's config.
`DELETE`	`/v1/monitors/:id`	–	Delete a monitor.

Schedules (cron-driven runs)

Method	Path	Body	Description
`GET`	`/v1/schedules`	–	List schedules.
`POST`	`/v1/schedules`	`{ cronExpr, operation, config, isActive? }`	Create a schedule.
`GET`	`/v1/schedules/:id`	–	Fetch a schedule.
`PATCH`	`/v1/schedules/:id`	Partial schedule	Update.
`DELETE`	`/v1/schedules/:id`	–	Delete.
`POST`	`/v1/schedules/:id/run`	–	Manually trigger a scheduled run.

Recipes

Authoring surface for reusable pipelines.

Method	Path	Body	Description
`GET`	`/v1/recipes`	–	List the caller's recipes.
`POST`	`/v1/recipes`	`{ name, matchPattern, options, isPublic? }`	Create.
`GET`	`/v1/recipes/:id`	–	Fetch.
`PATCH`	`/v1/recipes/:id`	–	Update.
`DELETE`	`/v1/recipes/:id`	–	Delete.

Traces (Studio-backed pipeline replay)

Every pipeline run produces a trace. Traces can be inspected, shared, and replayed.

Method	Path	Body	Description
`GET`	`/v1/traces`	–	List recent traces (paginated).
`POST`	`/v1/traces`	`{ uri, durationMs, storageKey }`	Register a trace (internal; CLI uses this).
`GET`	`/v1/traces/:id`	–	Fetch a trace.
`GET`	`/v1/traces/:id/share`	–	Generate a one-time share URL for the trace.
`DELETE`	`/v1/traces/:id`	–	Delete a trace.

Jobs (async work queue)

Long-running extract / act / sense operations run as jobs.

Method	Path	Body	Description
`GET`	`/v1/jobs`	`?status=&type=&limit=`	List jobs.
`GET`	`/v1/jobs/:id`	–	Fetch a job and its current status.

API keys

Programmatic management of API keys – dashboard-authenticated users call these with a JWT.

Method	Path	Body	Description
`GET`	`/v1/keys`	–	List keys (redacted).
`POST`	`/v1/keys`	`{ name, rateLimit? }`	Create a new key. Returns the full key once.
`DELETE`	`/v1/keys/:id`	–	Revoke a key.

Auth

Method	Path	Body	Description
`POST`	`/v1/auth/signup`	`{ email, password }`	Create an account. No auth.
`POST`	`/v1/auth/login`	`{ email, password }`	Exchange credentials for a JWT. No auth.
`GET`	`/v1/auth/me`	–	Return the authenticated user profile.

Dashboard

Aggregated reads for the hosted dashboard (/v1/dashboard/*). Not public API surface – subject to change.

Method	Path	Description
`GET`	`/v1/dashboard/stats`	Usage overview.
`GET`	`/v1/dashboard/usage`	Time-series credit usage.

Common patterns

Rate limiting

Every API key has a requestsPerMinute ceiling. When you exceed it, the server returns 429 Too Many Requests with a Retry-After header.

Idempotency

Mutation routes (/v1/act) honour an optional Idempotency-Key header. When two requests share the same key, the second returns the cached receipt from the first – no re-execution.

Errors

Errors follow a consistent shape:

JSON

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Action blocked by policy rule 'No destructive ops on prod'.",
    "phase": "act"
  }
}

HTTP status codes match REST conventions: 400 for bad input, 401 for missing auth, 403 for auth-present-but-denied, 404 for missing resources, 409 for conflicts, 422 for validation, 429 for rate limits, 500 for server errors.

OpenAPI

The full OpenAPI 3.1 spec is served at /openapi.json (backlog – see IDEAS.md under the Page 2 + Page 3 backlog for the auto-gen story). Until it lands, this page is the authoritative reference.

What's next

MCP-First Pipeline – same surface exposed as MCP tools.
Reference: CLI – same surface as CLI subcommands.
Concepts: Act – signed receipts + policy + idempotency, the details behind /v1/act.