Docs / API Keys & Rate Limits

API Keys & Rate Limits

aqoon uses API keys to authenticate programmatic access to the search API, MCP server, and other developer endpoints. Keys are prefixed with aqn_ followed by 40 random characters, and are stored server-side as SHA-256 hashes — the plaintext is only shown once at creation time.

To create and manage your keys from the UI, see the User Guide.

Key Types

There are two key types with different access scopes:

Type Access Scope Typical Use
Full-access All collections owned by or subscribed to the key owner Personal MCP integration, automation scripts, internal tooling
Scoped Only collections explicitly granted to the key Sharing search access with third-party developers or applications

Scoped keys are the safer default when distributing access. Grant access to specific collections via the key management UI or the /api/v1/keys/{uuid}/collections/ endpoint.

Permission Levels

Each collection access grant on a scoped key carries a permission level that controls what the key holder can do with that collection:

Permission Allowed Operations
read Search and retrieve documents from the collection
write Search, retrieve, and upload new documents to the collection

The default permission for a new grant is read. Pass "permission": "write" when granting access if the key holder needs to upload documents.

Full-access keys have implicit write permission on all collections owned by the key owner — no grant is required.

Grant / Revoke Collection Access

Use the /api/v1/keys/{uuid}/collections/ endpoint to manage which collections a scoped key can reach, and at what permission level.

Grant access

POST /api/v1/keys/{uuid}/collections/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "collection_id": "collection-uuid",
  "permission": "write"
}

Omit permission (or pass "read") to grant read-only access. Pass "write" to allow document uploads as well.

Revoke access

DELETE /api/v1/keys/{uuid}/collections/{collection_id}/
Authorization: Bearer aqn_your_api_key

Key rotation (generating a new secret for an existing key record) preserves all collection grants and their permission levels. The new secret is a drop-in replacement — no re-granting is required.

Write permission is required to use the document upload API (POST /api/v1/collections/{id}/documents/). Requests from a key with only read access will be rejected with HTTP 403.

Key Expiration

Keys can be created with an expiration date (30 days, 90 days, 6 months, or 1 year) or set to never expire. You can change the expiration at any time from the key detail page.

Expired keys are automatically rejected with a 401 error. To renew a key, set a new expiration from the key detail page. No new key needs to be created.

Search Endpoint

The developer search endpoint accepts a Bearer token and returns ranked result chunks from all collections accessible to the key:

POST /api/v1/search/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "query": "your search query",
  "limit": 5,
  "collection_id": "optional-uuid-to-scope-to-one-collection"
}

Example with cURL:

curl -X POST https://your-instance/api/v1/search/ \
  -H "Authorization: Bearer aqn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "retrieval augmented generation", "limit": 10}'

See the API Reference for full request/response schemas, filtering options, and error codes. Use the Search Playground to test interactively.

Rate Limiting

Each API key is assigned a rate tier that controls how many requests can be made across three windows:

Tier Per Minute Per Day Per Month
Free (default) 10 1,000 10,000
Basic 60 10,000 100,000
Pro 300 100,000 1,000,000

Rate tiers are managed by your account administrator. Limits are enforced per account — all API keys owned by the same user share a single set of counters. Every API response includes the following headers so your application can track limits programmatically:

Header Description
X-RateLimit-Limit Maximum requests allowed in the current window
X-RateLimit-Remaining Requests remaining in the current window
Retry-After Seconds to wait before retrying (only present on 429 responses)

When a limit is exceeded, the API returns HTTP 429 Too Many Requests. Your client should respect Retry-After and implement exponential backoff for resilience.

Usage Dashboard

The usage dashboard is available in the app sidebar under API Usage. It provides:

  • Summary metrics — Total requests, error count, and average response time for the selected period
  • Daily volume chart — Requests and errors plotted over 7, 30, or 90 days
  • Per-key breakdown — Request counts and error rates per API key
  • Recent request log — Query text, result count, response time, and HTTP status for individual requests

Webhook Notifications

Configure a webhook URL to receive notifications when documents finish processing. Instead of polling for status, aqoon will POST a signed JSON payload to your URL when a document is indexed or failed.

  • One webhook per organization — set via POST /api/v1/webhooks/
  • HMAC-SHA256 signed — verify authenticity using the secret returned at creation
  • Automatic retries — exponential backoff on server errors (max 5 retries)
  • Test endpoint — send a test event via POST /api/v1/webhooks/test/

See the API Reference — Webhooks for full payload format, signature verification, and examples.

Billing & Pricing

API query volume is metered against your monthly plan quota. Three plans are available:

Plan Price Included Queries/Month Overage Rate
Free $0/mo 1,000 —
Starter $29/mo 10,000 $0.002 per query
Pro $99/mo 100,000 $0.001 per query

Billing is managed via Stripe. Invoices are generated automatically at the end of each billing cycle based on actual usage data. Overage charges are only applied when you exceed the included quota for your plan.