Overview · Qualia

The Qualia API is a JSON REST API. This page covers what every request has in common. The endpoint pages that follow are generated from the OpenAPI spec.

Base URL

https://qualia.so/v1

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer qk_live_...

Keys start with qk_live_ and belong to your organization. Create and revoke them in Settings → API Keys. A missing, malformed, or revoked key returns 401. To test a key, call GET /v1/ping. See Manage API keys.

Endpoints

Method	Path	Description	SDK method
`POST`	`/v1/actors`	Create an actor. Sends a signup to Qualia.	`createActor`
`GET`	`/v1/actors/{actorId}`	Fetch an actor. Returns its status, briefing, and score.	`getActor`
`GET`	`/v1/ping`	Check an API key. Uses no credits and does not count toward the rate limit.	`ping` (SDK 0.2.0 or later)

Requests and responses

Send request bodies as JSON with Content-Type: application/json.
Responses are JSON encoded as UTF-8.
Timestamps are ISO 8601 strings in UTC, such as 2026-09-29T14:02:11.482Z.
IDs are opaque strings. Store them as they are and do not parse them.
Fields with no value are null. They are never left out.

Idempotency

POST /v1/actors is idempotent on email within your organization. The first request for an email returns 201 Created with "status": "created". Every later request for the same email returns 200 OK with "status": "already_exists" and the original actorId, without starting new research. You can retry it safely. GET requests change nothing and are always safe to retry.

Actors explains what happens to the fields in a repeat request.

Errors

Errors return an HTTP status and a JSON body:

{
  "error": {
    "code": "not_found",
    "message": "Actor not found",
    "requestId": "req_x2f9kq7wz1mv8c3jtr0hbnyd"
  }
}

Handle errors and rate limits lists every code and how to recover.

Limits

Limit	Value	When you exceed it
Rate limit	60 requests per minute per API key, shared by `POST /v1/actors` and `GET /v1/actors/{actorId}`	`429` with a `Retry-After` header
Briefing credits	One credit per briefing	`402` on `POST /v1/actors`
Request body size	1 MB	`413`

Successful responses from the actor endpoints include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Rate limits explains them. Credits explains when a signup uses a credit.

Versioning

The version is part of the path: /v1. Qualia adds to /v1 without breaking it: new endpoints, new optional request fields, new response fields, and new error codes. Write your code so it ignores fields and values it does not recognize. Breaking changes ship under a new version path, such as /v2.

SDK

The TypeScript SDK wraps every endpoint with typed methods. ping() and the typed 402, 413, and 429 errors need version 0.2.0 or later. Install it with npm install @qualiaso/sdk.

On this page