Developer Documentation

Getting Started

AIrchives provides a simple REST API for storing and retrieving structured memories for AI agents and applications. All requests require an X-NomeAI-User-Id header for authentication.

Base URL: https://api.airchives.dev

Authentication

Include your user ID in the X-NomeAI-User-Id header with every request. Format: airchives:user_xxx

Tenant Boundary (Business)

For business integrations, AIrchives supports multi-tenant isolation. A tenant_id groups end-users under a single billing and administrative boundary.

Tenant ID Resolution

The API resolves tenant_id in the following order:

  1. If X-NomeAI-Tenant-Id header is present, use it
  2. Else, if X-NomeAI-User-Id matches pattern tenant:<tenant_id>:user:<...>, extract tenant_id
  3. Else, tenant is unknown

Tenant ID format constraint: ^[a-z0-9-]+$ (lowercase alphanumeric and hyphens only)

Behavior When Tenant is Unknown

Normal APIs (/memory/*, /usage) still work with user_id boundary only. Admin ops (/admin/*) require tenant_id and will reject requests with HTTP 400.

Recommended ID Practices

Use non-PII user identifiers (UUID, HMAC hash, or opaque strings) instead of emails or personal data.

Pattern A (preferred): Set both headers separately

X-NomeAI-Tenant-Id: acme-corp
X-NomeAI-User-Id: usr_a1b2c3d4

Pattern B: Encode tenant in user_id (no separate tenant header)

X-NomeAI-User-Id: tenant:acme-corp:user:usr_a1b2c3d4

AIrchives auto-registers (tenant_id, user_id) pairs into the tenant_users table on normal API usage.

Memory Types

Memories can be organized into layers using the memory_type field. This enables structured retrieval based on the nature of the information.

  • episode (default): Conversational memories and individual interactions
  • profile: Long-term user preferences and characteristics
  • project: Project-specific context and technical details

Note: Profile-based retrieval is opt-in. Only profile=default is supported for now.

Endpoints

Check Usage (Free)

curl -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  https://api.airchives.dev/usage

Returns credit balance. New users receive 200 free credits.

Save Memory (1 credit)

Basic save (defaults to episode type):

curl -X POST \
  -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"content": "User prefers dark mode UI"}' \
  https://api.airchives.dev/memory/inbox

Save with memory_type:

curl -X POST \
  -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"content": "User is a TypeScript developer", "memory_type": "profile"}' \
  https://api.airchives.dev/memory/inbox

Save with full metadata:

curl -X POST \
  -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "Project uses React 18 with TypeScript",
    "memory_type": "project",
    "concept_cluster": "Tech Stack",
    "topic_tags": ["react", "typescript"],
    "importance_hint": 0.8
  }' \
  https://api.airchives.dev/memory/inbox

Search Memories (1 credit)

Get all memories (default behavior):

curl -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  https://api.airchives.dev/memory/context

Use layered retrieval with profile=default:

curl -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  'https://api.airchives.dev/memory/context?profile=default'

Fetches from episode (60%), profile (20%), and project (20%) buckets, then merges results.

Filter by memory_type:

curl -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  'https://api.airchives.dev/memory/context?memory_type=episode'

Filter with limit:

curl -H 'X-NomeAI-User-Id: airchives:user_xxx' \
  'https://api.airchives.dev/memory/context?memory_type=profile&limit=10'

Response Format

Memory context response:

{
  "status": "ok",
  "user_id": "airchives:user_xxx",
  "profile": "default",
  "memories": [
    {
      "id": 123,
      "content": "User prefers dark mode UI",
      "concept_cluster": null,
      "topic_tags": [],
      "intent": null,
      "importance_hint": null,
      "memory_type": "episode",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Business Admin Ops

These endpoints are for tenant administrators to manage end-users and their data. They are protected by admin authentication (Bearer token) and require tenant_id resolution. All admin endpoints are separate from end-user APIs.

Admin operations charge credits to the tenant billing account (tenant:<tenant_id>), not to individual end-users.

List Users (Free)

Returns recent end-users for the tenant, ordered by last_seen_at.

curl -H 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  -H 'X-NomeAI-Tenant-Id: acme-corp' \
  'https://api.airchives.dev/admin/users?limit=50'

Query param: limit (default 50, max 50)

Response:

{
  "status": "ok",
  "tenant_id": "acme-corp",
  "limit": 50,
  "count": 2,
  "users": [
    { "user_id": "usr_abc", "created_at": "...", "last_seen_at": "..." },
    { "user_id": "usr_xyz", "created_at": "...", "last_seen_at": "..." }
  ]
}

Export User Memories (5 credits)

Exports all memories for a specific end-user. Requires tenant boundary membership.

curl -H 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  -H 'X-NomeAI-Tenant-Id: acme-corp' \
  https://api.airchives.dev/admin/users/usr_abc/export

Returns 404 if user is not found in the tenant. Returns 402 if tenant has insufficient credits.

Response:

{
  "status": "ok",
  "tenant_id": "acme-corp",
  "user_id": "usr_abc",
  "count": 15,
  "memories": [
    { "id": 123, "content": "...", "memory_type": "episode", ... }
  ]
}

Delete All User Memories (5 credits)

Deletes all memories for a specific end-user. Audit-safe: usage_logs are preserved.

curl -X DELETE \
  -H 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  -H 'X-NomeAI-Tenant-Id: acme-corp' \
  https://api.airchives.dev/admin/users/usr_abc/memories

Returns 404 if user is not found in the tenant. Returns 402 if tenant has insufficient credits.

Response:

{
  "status": "ok",
  "tenant_id": "acme-corp",
  "user_id": "usr_abc",
  "deleted_count": 15
}

Batch Delete Specific Memories (5 credits)

Deletes specific memory entries by ID. Max 50 IDs per request.

curl -X DELETE \
  -H 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  -H 'X-NomeAI-Tenant-Id: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [123, 456, 789]}' \
  https://api.airchives.dev/admin/users/usr_abc/memories/batch

Returns 400 if more than 50 IDs. Returns 404 if user is not found in the tenant. Returns 402 if tenant has insufficient credits. Empty array is a no-op (no billing, but tenant boundary is still enforced).

Response:

{
  "status": "ok",
  "tenant_id": "acme-corp",
  "user_id": "usr_abc",
  "requested_count": 3,
  "deleted_count": 2,
  "not_deleted_ids": [789]
}

Machine-Readable API Spec

For AI agents that need to parse the API specification programmatically, a JSON schema is available at /ai.json

Pricing

Normal developer-facing endpoints consume credits per call as shown below. Admin operations (export, delete, batch delete) consume 5 CR per request, charged to the tenant account.

  • Save memory: 1 credit
  • Search memory: 1 credit
  • Check usage: Free
  • List users (admin): Free
  • Export user memories (admin): 5 credits
  • Delete all user memories (admin): 5 credits
  • Batch delete memories (admin): 5 credits
  • New users: 200 free credits