API Reference

Tenant Management

Build multi-tenant applications with isolated memory stores for each of your customers. One API key controls all tenants, with billing rolled up to your organization.

Tenant Isolation

Each tenant has completely isolated memory data

Auto-Creation

Tenants are created automatically on first API call

Shared Pool Billing

All usage counts against your organizations plan

Multi-Tenant Architecture

Tenants are customer organizations you create under your parent organization. Pass tenantId to any memory endpoint to operate on that tenant's isolated data store. Your API key grants access to all tenants under your organization.

Base URL

$https://memory.hypersparkai.com//api/v1/tenants

GET/api/v1/tenants

List Tenants

Retrieve all tenant organizations under your parent organization with usage statistics.

Headers

Header	Value	Required
Authorization	Bearer <api_key>	Yes

Example Request

curl -X GET "https://memory.hypersparkai.com//api/v1/tenants" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "tenants": [
    {
      "id": "org_abc123xyz",
      "name": "Acme Corporation",
      "slug": "acme-corp",
      "displayName": "Acme Corporation",
      "status": "active",
      "queryLimit": null,
      "queriesThisPeriod": 1523,
      "memoryCount": 4521,
      "lastActiveAt": "2024-12-30T14:22:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

POST/api/v1/tenantsadmin

Create Tenant

Create a new tenant organization under your parent organization.

Request Body

Parameter	Type	Required	Description
name	string	Yes	Display name (max 100 chars)
slug	string	No	URL-friendly ID (lowercase, hyphens, max 50 chars)

Example Request

curl -X POST "https://memory.hypersparkai.com//api/v1/tenants" \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme-corp"
  }'

Response

{
  "success": true,
  "tenant": {
    "id": "org_abc123xyz",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "displayName": "Acme Corporation",
    "status": "active",
    "queryLimit": null,
    "memoryCount": 0,
    "userCount": 0,
    "createdAt": "2024-12-31T10:30:00Z",
    "updatedAt": "2024-12-31T10:30:00Z"
  },
  "tenantId": "org_abc123xyz"
}

GET/api/v1/tenants/:tenantId

Get Tenant Details

Retrieve detailed information about a specific tenant organization.

Path Parameters

Parameter	Type	Description
tenantId	string	The unique tenant organization ID

Auto-Creation Behavior

If the tenant doesn't exist, it will be automatically created with default settings. This enables frictionless tenant provisioning—simply start making API calls with a newtenantIdand the tenant will be created on first access.

Example Request

curl -X GET "https://memory.hypersparkai.com//api/v1/tenants/org_abc123xyz" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

{
  "success": true,
  "tenant": {
    "id": "org_abc123xyz",
    "name": "Acme Corporation",
    "slug": "acme-corp",
    "displayName": "Acme Corporation",
    "status": "active",
    "queryLimit": 10000,
    "usageResetDay": 1,
    "notes": "Enterprise customer - priority support",
    "parentOrganizationId": "org_parent123",
    "orgType": "tenant",
    "memoryCount": 4521,
    "userCount": 45,
    "lastActivity": "2024-12-30T14:22:00Z",
    "lastActiveAt": "2024-12-30T14:22:00Z",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-12-30T14:22:00Z"
  }
}

PATCH/api/v1/tenants/:tenantIdadmin

Update Tenant

Update a tenant organization's name or slug.

Request Body

Parameter	Type	Description
name	string	New display name (max 100 chars)
slug	string	New URL-friendly identifier

Example Request

curl -X PATCH "https://memory.hypersparkai.com//api/v1/tenants/org_abc123xyz" \
  -H "Authorization: Bearer hsmem_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp International"
  }'

Response

{
  "success": true,
  "tenant": {
    "id": "org_abc123xyz",
    "name": "Acme Corp International",
    "slug": "acme-corp",
    "displayName": "Acme Corp International",
    "status": "active",
    ...
  }
}

DELETE/api/v1/tenants/:tenantIdadmin

Delete Tenant

Permanently delete a tenant organization and all its associated data.

Destructive Action

This action is irreversible. All memories, users, and usage data for this tenant will be permanently deleted.

Example Request

curl -X DELETE "https://memory.hypersparkai.com//api/v1/tenants/org_abc123xyz" \
  -H "Authorization: Bearer hsmem_your_api_key"

Response

Returns HTTP 204 No Content on success.

Automatic Tenant Creation

You don't need to explicitly create tenants before using them. When you pass a new tenantId to any memory endpoint (like /api/v1/memory/ingest), the tenant is automatically created on first use.

// First call with new tenantId auto-creates the tenant
await fetch('https://memory.hypersparkai.com//api/v1/memory/ingest', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hsmem_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tenantId: 'my-new-customer',  // Created automatically!
    userId: 'user_123',
    messages: [{ role: 'user', content: 'Hello world' }]
  })
});

Error Responses

Status	Error	Description
401	Unauthorized	Invalid or missing API key
403	Forbidden	Missing admin scope or no access to tenant
404	Not Found	Tenant does not exist
429	Query Limit Exceeded	Tenant has exceeded its per-tenant query limit

API Overview