API reference
Who am I
Verify an API key and read its workspace, plan, access state, limits, and current usage in one call.
Returns the workspace, commercial plan, access state, key metadata, and - when event limits are enforced - current monthly usage for the presented API key. One call proves the key works and shows what it is attached to, which makes it the natural first request for integration setup and for coding agents verifying a pasted key.
Responses are never cached (
Authentication
Send your API key inX-Pylva-Key. Rate limit is shared with the telemetry endpoints (1000 requests/min per key).
curl https://api.pylva.com/api/v1/whoami \
-H "X-Pylva-Key: $PYLVA_API_KEY" \
-H "X-Pylva-Contract-Version: 2"
Response
{
"org": { "slug": "acme", "name": "Acme" },
"plan": "pro",
"access_state": "active",
"key": { "id": "deadbeef", "scope": "universal" },
"limits": { "monthly_events": 1000000, "enforced": true },
"usage": {
"monthly_events_used": 1234,
"monthly_events_limit": 1000000,
"window_start": "2026-07-01T00:00:00.000Z",
"window_end": "2026-08-01T00:00:00.000Z",
"window_source": "calendar_month"
},
"docs_url": "https://docs.pylva.com",
"agent_setup_url": "https://docs.pylva.com/setup-with-ai.md"
}
| Field | Notes |
|---|---|
org.slug, org.name | The workspace this key belongs to. |
plan | pro, scale, enterprise, or null when no commercial plan is active. See Plans and limits. |
access_state | checkout_required, active, or suspended. Non-active workspaces cannot use product or ingestion APIs. |
tier | Deprecated compatibility alias for plan; emitted only for active paid workspaces when X-Pylva-Contract-Version is absent or older than 2. |
key.id | The public key identifier - never the secret. |
key.scope | Current Pylva Cloud keys report universal; legacy keys are upgraded to the same capability. |
limits.monthly_events | The active commercial-plan cap, or the configured self-hosted cap; null means no event cap. |
limits.enforced | Whether event-cap enforcement is enabled. It is true by default for hosted and self-hosted deployments; self-host operators can explicitly set ENABLE_EVENT_LIMITS=false. |
usage | null when limits are not enforced, when there is no event cap, or if the lookup fails open - use limits.enforced to tell these apart. |
Cache-Control: no-store).
Clients that consume plan and access_state should send
X-Pylva-Contract-Version: 2. During the compatibility window, missing or
older declarations are counted conservatively as legacy tier consumers. That
authenticated usage signal is the removal gate for the deprecated alias.
Successful responses repeat X-Pylva-Contract-Version: 2. The declaration and
response header are optional metadata only; neither authorizes a request or
changes the workspace entitlement.
Notes
- A
401 INVALID_API_KEYhere means the key is wrong or revoked - the same check as any other endpoint, but with a useful body on success. - Full schema: api.pylva.com/openapi.json.