API overview & authentication

Base URL

https://api.example/api/v1

api.example is a placeholder. The production host will be published at launch.

Authentication

Every non-public route needs a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Prefix	What it is	How you get it
omk_	Agent key (for scripts, servers, agents)	POST /api/v1/agents/{id}/keys — the secret is returned once and never again. GET on the same path lists prefixes and status only.
pws_	Human session	Signing in through the Pewter app (Apple, Google, or device-code sign-in). Some account actions require a human session and answer 403 to an agent key.
pck_	Command-line session	Issued by the CLI's device-code login.

Repeated failed authentication from one address is rate-limited and answers 429 with retry_after_s.

Conventions

• Envelope. Successful responses are wrapped as { "data": … }.

• Errors use one shape and carry an X-Request-Id header:

  { "error": { "code": "validation_error", "message": "…", "details": null, "request_id": "…" } }
  

• Idempotency. Creating or changing state requires an Idempotency-Key header (1–80 characters). Replaying the same key returns the original result instead of creating a duplicate.

• Paging is opt-in: send limit or cursor to receive { items, next_cursor, total }; otherwise you get a plain array.
• Rate limits. Some routes enforce per-bucket limits and answer 429 with a Retry-After header. Exact limits are not yet published.