---
title: Supernova API
description: Automate Supernova through an unversioned HTTPS API with scoped bearer credentials and structured errors.
species: reference
---
# Supernova API

Use `https://api.supernova.ai` to query data, inspect the catalog, manage sources, follow runs, trigger sends, read logs and usage, and manage personal access tokens.

```bash
curl https://api.supernova.ai/whoami \
  -H "Authorization: Bearer pat_..."
```

## Contract

API paths do not contain a version segment. Responses include `Supernova-Version` for observation and `Request-Id` for support. Additive response fields may appear; clients should ignore fields they do not understand.

Resource objects have an `object` discriminator and prefixed ids. Collections use `{"object":"list","data":[...]}` and expose `has_more` with a cursor when the resource is paginated.

## Resources

| Resource | Purpose |
|---|---|
| [Queries](/v2/docs/api/queries) | Submit SQL and retrieve Parquet or inline results |
| [Jobs](/v2/docs/api/jobs) | List, inspect, follow, cancel, and retrieve run results |
| [Catalog](/v2/docs/api/catalog) | List schemas and inspect table columns |
| [Sources](/v2/docs/api/sources) | List, create, change, test, and delete sources |
| [Syncs](/v2/docs/api/sync) | Start a source sync and follow progress |
| [Sends](/v2/docs/api/sends) | Inspect and control configured sends |
| [Logs](/v2/docs/api/logs) | Read source errors and schema changes |
| [Usage](/v2/docs/api/usage) | Read monthly metered usage and projected cost |
| [PATs](/v2/docs/api/pats) | Create, list, and revoke personal access tokens |

## Rate limits

Each caller may make 120 requests per minute. Each organization may make 600 per minute across callers. A `429 rate_limited` response includes `Retry-After` in seconds. Polling and stream reconnections count as requests.

## Idempotency

Mutation endpoints that advertise idempotency accept `Idempotency-Key`. A replay under the same principal and organization returns the original resource. Reusing a key with different input returns a `409` rather than guessing which operation you intended.