API conventions

The rules that hold across every endpoint. They are factored out here so the per-namespace reference pages can stay focused on what makes each one different.

Base URL

https://api.pulp.dev/v1. All requests go over HTTPS, and all bodies are JSON.

Authentication

Bearer keys in the Authorization header. pk_test_ keys are free, sandboxed, and rate-limited generously enough to build a real prototype. pk_live_ keys meter against your plan. See Getting started for setup.

Versioning

Date-pinned per key (for example 2026-07-01). We will never move your integration under you; you upgrade when you choose.

Idempotency

Send an Idempotency-Key header on any write and retries become safe. Simulations are expensive thoughts; you should never pay for the same one twice because a router blinked.

Errors

Machine-readable, human-decent. Every error carries a stable type and code, a plain-language message, and a link to the relevant docs.

{
  "error": {
    "type": "invalid_request",
    "code": "persona_space_missing",
    "message": "TrueAura personas require all six spaces. Missing: mindstate.",
    "doc": "https://docs.pulp.dev/windfall/trueaura#mindstate"
  }
}

Webhooks

Subscribe to simulation.completed, batch.finished, score.threshold_crossed, and friends. Payloads are signed; verification is one SDK call.

Rate limits

Radiance calls are cheap and limited high. Windfall simulations are metered by persona-message pairs. ServerCore batch is queued, not limited. Headers tell you where you stand on every response.

SDKs

Pulp ships two first-party SDKs over one HTTP API: the Python SDK for server-side work (Radiance, Windfall, Groundwater) and loosethreads UI, the React component library for the web. Every server-side example in this documentation is Python.

Back to the Server-Side SDK, or the documentation home.