Public API

The Public API is a machine-to-machine HTTP API for uploading files, checking their processing status, and searching your library. It is available to teams with an active Pro subscription.

Endpoint summary

Method	Path	Scope	Purpose
`POST`	`/api/v1/files`	`upload`	Upload one file, up to 100 MiB.
`GET`	`/api/v1/files/:fileId`	`upload` or `search`	Read file metadata and status.
`POST`	`/api/v1/search`	`search`	Search and filter the team library.

The base URL is your New Archive deployment followed by /api/v1:

text

https://your-host/api/v1

JSON is used for requests and responses, except for file uploads, which use multipart/form-data. Download the machine-readable OpenAPI 3.1 specification for client generation and contract inspection.

Quick start

Create a key under Settings → API keys, then store the host and secret in environment variables. The secret starts with na_ and is shown only once.

bash

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

Upload a file:

bash

curl --fail-with-body \
  -X POST "$NEW_ARCHIVE_URL/api/v1/files" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY" \
  -F "file=@sunset.jpg"

The API returns 202 Accepted while processing continues asynchronously:

json

{
  "id": "0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b",
  "version_id": "0198c9a0-8a12-7e55-9c01-d4b6f7a8e9c0",
  "status": "processing"
}

Search the library:

bash

curl --fail-with-body \
  -X POST "$NEW_ARCHIVE_URL/api/v1/search" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"sunset at the beach","limit":10}'

Guides

Authentication covers keys, scopes, permissions, plan access, and rate limits.
Uploading files covers direct upload, response fields, and processing-status polling.
Searching covers ranking, every filter, and cursor pagination.
Upload limits explains the current 100 MiB public-API limit and how it differs from the app uploader.
Errors documents the stable error envelope, every error code, and retry handling.

Current boundaries

Version 1 does not provide OAuth, original-file downloads, facet listings, find-similar search, or a public presigned multipart upload flow. Ready files include short-lived signed thumbnail URLs. Files larger than 100 MiB must currently be uploaded through the app.

PreviousKeyboard shortcuts NextAuthentication