Pylva API Overview

Pylva is SDK-first. Most teams should use the TypeScript or Python SDK instead of calling the API directly. For first-run SDK issues such as invalid keys, missing dashboard events, pricing warnings, and budget hard stops, see Troubleshooting.

Base URL

https://api.pylva.com

Self-hosted deployments can use a different endpoint. See Open Source And Hosted when choosing between Pylva Cloud and self-hosting. GET /api/v1/health is public and reports service health; GET /api/v1/livez is a bare liveness probe.

Accounts, workspaces, and keys

An account (GitHub, Google, or magic-link identity) belongs to a workspace - called a “builder” in API responses, which reference builder_id. The workspace is created automatically at first sign-in, and all API keys are scoped to it.

Authentication

Pylva has one API key. Create it from Settings -> API keys and store it as PYLVA_API_KEY — it authenticates every machine endpoint: SDK telemetry, rules, pricing, budget sync, custom pricing, and data import. See API keys. Send it in either header — both are accepted on every endpoint:

# What the SDKs usually send; 200 means the key is valid
curl -s -o /dev/null -w "%{http_code}" \
  https://api.pylva.com/api/v1/rules \
  -H "X-Pylva-Key: $PYLVA_API_KEY"

# What the pylva CLI sends
curl https://api.pylva.com/api/v1/cost-sources \
  -H "Authorization: Bearer $PYLVA_API_KEY"

New keys use the pv_live_* prefix; legacy pv_cli_* keys remain valid everywhere. Prefixes carry no permission meaning.

Errors

Every non-2xx response uses one envelope shape:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Status	Code	Meaning
400	`VALIDATION_ERROR`	Malformed JSON or wire-schema violation; `param` names the offending field path.
401	`INVALID_API_KEY`	Missing, malformed, or revoked key.
403	`TIER_LIMIT_REACHED`	Monthly event cap reached; the `X-Pylva-Tier-Usage: current/limit` header shows where you stand. Not a 402. See Plans and limits.
429	`RATE_LIMIT_EXCEEDED`	Over the per-key rate limit; `Retry-After` gives the wait in seconds.

Older deployments may still return 403 WRONG_SCOPE for a valid key used with a mismatched legacy endpoint family. Current Pylva releases accept any valid API key on every machine endpoint.

Rate limits

Endpoint family	Limit
Telemetry, rules, pricing, and budget sync	1000 requests/min per key, shared across these endpoints
Custom pricing and other control-plane endpoints	100 requests/min per key
Cost-source import	100 requests/min per key

API surfaces

The SDK-facing API is machine-readable at api.pylva.com/openapi.json and includes:

Who am I - verify a key and read workspace, plan, access state, and usage.
Submit telemetry events.
Sync rules.
Fetch pricing.
Sync budget accumulators.

The custom-pricing and data-import surfaces are documented manually in Mintlify:

Get started

SDKs

Concepts

API reference

Pylva API Overview

Base URL

Accounts, workspaces, and keys

Authentication

Errors

Rate limits

API surfaces

​Base URL

​Accounts, workspaces, and keys

​Authentication

​Errors

​Rate limits

​API surfaces

Base URL

Accounts, workspaces, and keys

Authentication

Errors

Rate limits

API surfaces