API Reference
Every endpoint Qualia exposes.
The Qualia API is a REST API at https://qualia.so/v1. JSON in, JSON out. Every operation page below is generated from the OpenAPI spec.
Authentication
Authorization: Bearer qk_live_...API keys are issued per organization. Create them in Settings → API Keys. The plaintext is shown once on creation; store it securely.
Base URL
https://qualia.so/v1Idempotency
POST /v1/actors is idempotent on the email field, scoped to your organization. Posting an email that already exists in your organization returns the original actor instead of creating a new one. The response status is 200 instead of 201, and the body's status is already_exists. If you submit different fields (such as a new name or metadata) for an email that already exists, the existing actor is returned and the submitted fields are ignored. GET requests are naturally safe to retry.
Errors
Every error response is { error: { code, message, requestId } }. The code is a stable machine identifier, the message is human-readable, and the requestId correlates with our logs (include it when filing a support ticket). See the errors guide for the full matrix.
No request quota is enforced on /v1/* today. Quotas and Retry-After headers will ship before general availability and will be documented here.
Versioning
The Qualia API uses path versioning at /v1. Non-breaking changes ship inline on /v1: new endpoints, new optional request fields, new response fields, and new error.code values. Breaking changes ship as /v2 with a separate path prefix and a deprecation timeline for the prior version. Treat unknown response fields as additive and parse defensively.
Next
- Create an actor.
POST /v1/actors. - Fetch an actor.
GET /v1/actors/{actorId}. - Errors guide. Status codes, stable codes, and recovery.