Authentication

Overview

All requests to the Notery public API (/api/v1/*) must include a valid API key in the Authorization header. API keys are scoped to a single workspace and carry the permissions of the user who created them.

Base URL

https://notery.dev

If you are running a self-hosted instance, replace this with your instance's URL (e.g. http://localhost:3000 during local development).

Authentication Header

Every request must include the Authorization header with a Bearer token:

Authorization: Bearer ntry_<your-api-key>

API keys always start with the ntry_ prefix. You can create and manage keys from the API Keys page in your workspace settings.

Example Request

curl -s https://notery.dev/api/v1/documents \
  -H "Authorization: Bearer ntry_abc123def456..."

Response Format

All successful responses follow a consistent envelope structure:

{
  "data": { ... }
}

For list endpoints, data is an array. For single-resource endpoints, data is an object.

Error Responses

When a request fails, the API returns a JSON error with an appropriate HTTP status code:

Error response body:

{
  "statusCode": 401,
  "message": "Missing or invalid Authorization header"
}

Common 401 Scenarios

• The Authorization header is missing entirely.
• The header does not use the Bearer scheme.
• The API key is not recognized (e.g. it was revoked or never existed).
• The API key has passed its expiration date.

Common 403 Scenarios

• A free-plan workspace has more documents than the plan allows, which disables search. Upgrade to Pro to re-enable it.

Rate Limiting

API requests are subject to rate limits that vary by plan. If you exceed your rate limit, the API returns a 429 Too Many Requests response. Back off and retry after a brief delay.

Key Expiration

API keys can optionally have an expiration date set when they are created. Once expired, the key is automatically rejected with a 401 response. You can create a new key at any time from the API Keys page.