Authentication

Every /api/v1 request requires an API key. Session cookies from the web app are not accepted on Public API routes.

Availability

The Public API requires an active Pro subscription. Key creation is disabled without API access, and every request checks the team's current entitlement. A valid key from a team without access receives 403 plan_required.

Create and store a key

Open Settings → API keys, choose a name, and grant one or both scopes. The secret starts with na_ and is displayed once. New Archive stores only its hash, so a lost key cannot be recovered; revoke it and create another.

Store the key outside source control:

bash
export NEW_ARCHIVE_URL="https://your-host"
export NEW_ARCHIVE_API_KEY="na_your_key"

Send the key

Use the HTTP Bearer scheme on every request:

http
Authorization: Bearer na_your_key
bash
curl --fail-with-body \
  "$NEW_ARCHIVE_URL/api/v1/files/0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY"

A missing, malformed, expired, or revoked key returns 401 unauthorized. A valid key without the required scope returns 403 forbidden.

Scopes and permissions

ScopeGrants
uploadUpload files and read their metadata or processing status.
searchSearch the library and read file metadata or processing status.

Scopes cannot be changed after creation. Create a replacement key when its access needs to change.

A key acts as the member who created it and is restricted to that member's team. Uploads are attributed to the creator. The upload scope is necessary but not sufficient: the creator's current team role must also grant files.upload. Revoking a key takes effect immediately.

Rate limit

Each key may make 120 requests in a 60-second window. A rejected request returns 429 rate_limited and may include a Retry-After header containing the number of seconds to wait.

http
HTTP/2 429
content-type: application/json
retry-after: 42

{"error":{"code":"rate_limited","message":"Rate limit exceeded"}}

Key safety

  • Keep keys in a secret manager or environment variable, never client-side browser code or a repository.
  • Give each integration its own narrowly scoped key.
  • Revoke unused or exposed keys immediately.
  • Treat request logs carefully: an Authorization header contains the full secret.
PreviousPublic APINextUploading files