API Reference

Public API surface for SDK consumers and third-party developers building integrations against PersonAIzer.

Authentication

Send your API key in the X-Api-Key header on every request:

X-Api-Key: pa_live_…

Create and manage keys in the dashboard at /api-keys. Each key is scoped to a single user account and shares that user's quota and rate limits.

Error envelope

All 4xx/5xx responses follow RFC 7807 Problem Details with Content-Type: application/problem+json. In addition to the standard type/title/status/detail fields, every response carries a stable string code extension (e.g. auth.unauthorized, knowledge.quota_exceeded, knowledge.invalid_external_id) — the canonical machine-readable error identifier; HTTP status alone is not enough to disambiguate.

Rate limits

Rate-limit policies are listed per-operation. When throttled the response is 429 with header Retry-After: <seconds> and body code: limits.rate_exceeded.

Idempotency

The batch upsert (PUT /api/knowledge/docs) and single upsert (PUT /api/knowledge/docs/by-external-id/{external_id}) are both idempotent when external_id is unchanged and content is identical — the server returns status: no_op and skips re-embedding. Safe to replay on retry or in a cron sync. Other mutation endpoints (PUT /api/personas/{id}/knowledge, DELETE) are also idempotent as stated per-operation.

Versioning

The current version is implicit v1 (no prefix in the URL). When breaking changes are required a new major version will be served at /api/v2/... alongside the existing one for a transition period; the old version stays available until announced sunset. Within a major version, only additive changes are made — new endpoints, new optional fields, new error codes — and consumers should ignore unknown fields. Endpoint deprecations are flagged via the OpenAPI deprecated: true marker and communicated via release notes before the change ships.

Correlation

Every response carries an X-Request-Id header. When you supply one on the request the same value is echoed back; otherwise the platform assigns one. Include it in support tickets so logs and traces can be located instantly.