> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenants

> Provision isolated customer resources, quotas, credits, and durable memory.

A tenant is the resource and billing boundary inside an environment. Use tenants to isolate each customer, workspace, or project while keeping them under one environment and API key strategy.

<Note>
  Core tenant endpoints are **\[User+Key]**. API keys need the scope shown below and remain limited to their environment and tenant allowlist. Durable-memory administration is **\[User]** only.
</Note>

## Endpoints

| Method   | Path                              | Description                    | Auth                         |
| -------- | --------------------------------- | ------------------------------ | ---------------------------- |
| `GET`    | `/tenants?env_id=`                | List tenants in an environment | \[User+Key] `tenants:read`   |
| `GET`    | `/tenants/:id`                    | Get a tenant and usage counts  | \[User+Key] `tenants:read`   |
| `POST`   | `/tenants`                        | Create a tenant                | \[User+Key] `tenants:write`  |
| `PATCH`  | `/tenants/:id`                    | Update a tenant                | \[User+Key] `tenants:write`  |
| `DELETE` | `/tenants/:id`                    | Delete a tenant                | \[User+Key] `tenants:delete` |
| `GET`    | `/tenants/:id/memory-settings`    | Get durable-memory settings    | \[User]                      |
| `PATCH`  | `/tenants/:id/memory-settings`    | Update durable-memory settings | \[User] admin                |
| `GET`    | `/tenants/:id/memories`           | List durable memories          | \[User]                      |
| `DELETE` | `/tenants/:id/memories/:memoryId` | Delete a durable memory        | \[User] admin                |
| `GET`    | `/tenants/:id/memories/graph`     | Get the memory entity graph    | \[User]                      |

For user sessions, `owner` and `billing_admin` can create, update, and delete tenants. API keys use scopes instead of organization roles. See [Tenancy](/developers/concepts/tenancy) and [Access & scopes](/developers/concepts/access-scopes).

***

### List tenants

`GET /tenants`

Returns tenants with knowledge-base, document, and storage usage counts.

<ParamField query="env_id" type="string">
  Environment to list. Required for a user session. With an API key, omit it to use the key's environment; if supplied, it must match that environment.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/tenants" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

<Warning>
  An empty `tenant_ids` allowlist on an API key means **all tenants in that key's environment**, not no tenants. List explicit IDs when the key should reach only selected tenants.
</Warning>

<Note>
  A key with `admin:full` lists every tenant in its environment even when `tenant_ids` contains explicit IDs. Use explicit permission scopes instead of `admin:full` when tenant-level discovery must remain restricted.
</Note>

***

### Get a tenant

`GET /tenants/:id`

Returns the tenant's configuration together with knowledge-base count, document count, and storage used.

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

***

### Create a tenant

`POST /tenants`

<ParamField body="environment_id" type="string" required>
  Environment that will own the tenant.
</ParamField>

<ParamField body="name" type="string" required>
  Tenant display name.
</ParamField>

<ParamField body="external_id" type="string">
  Stable identifier from your application, such as a customer or workspace ID.
</ParamField>

<ParamField body="external_name" type="string">
  Human-readable name from your application.
</ParamField>

<ParamField body="credits_pool" type="number">
  Credits to allocate from the organization to this tenant. Must be non-negative and cannot exceed the organization's available credits.
</ParamField>

<ParamField body="max_knowledge_bases" type="number">
  Maximum knowledge bases allowed for the tenant.
</ParamField>

<ParamField body="max_documents" type="number">
  Maximum documents allowed for the tenant.
</ParamField>

<ParamField body="max_storage_gb" type="number">
  Maximum tenant storage in gigabytes.
</ParamField>

<ParamField body="metadata" type="object">
  Application-defined metadata.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/tenants" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "ENVIRONMENT_ID",
    "name": "Acme workspace",
    "external_id": "customer_123",
    "credits_pool": 100,
    "max_knowledge_bases": 10,
    "max_documents": 1000,
    "max_storage_gb": 10
  }'
```

***

### Update a tenant

`PATCH /tenants/:id`

Updates any supplied tenant fields. Accepted fields are `name`, `external_id`, `external_name`, `credits_pool`, `max_knowledge_bases`, `max_documents`, `max_storage_gb`, and `metadata`.

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

***

### Delete a tenant

`DELETE /tenants/:id`

Deletes the tenant and the knowledge bases, documents, chats, agents, and other data it owns. Credit allocation is reconciled with the organization.

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

<Warning>
  Tenant deletion is irreversible. Confirm the tenant ID and export anything you need before deleting it.
</Warning>

## Durable memory

Memory management endpoints require a user session. Any organization member can read settings, memories, and the entity graph; only `owner` and `billing_admin` can change settings or delete a memory.

### Get memory settings

`GET /tenants/:id/memory-settings`

Returns the resolved `mode` and `retention` settings.

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

### Update memory settings

`PATCH /tenants/:id/memory-settings`

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

<ParamField body="mode" type="string">
  `disabled` or `durable`.
</ParamField>

<ParamField body="retention" type="string">
  `none`, `explicit_only`, or `automatic`. `explicit_only` stores facts only when a user explicitly asks AutoSage to remember them; `automatic` also retains useful context after conversations.
</ParamField>

```bash theme={null}
curl -X PATCH "https://api.autosage.ai/api/v1/tenants/TENANT_ID/memory-settings" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "durable", "retention": "automatic" }'
```

### List memories

`GET /tenants/:id/memories`

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of memories to return.
</ParamField>

<ParamField query="offset" type="number">
  Number of memories to skip.
</ParamField>

<ParamField query="q" type="string">
  Search text used to filter memories.
</ParamField>

When durable memory is disabled or unavailable, this endpoint returns a disabled result instead of failing the read flow.

### Delete a memory

`DELETE /tenants/:id/memories/:memoryId`

<ParamField path="id" type="string" required>
  Tenant ID.
</ParamField>

<ParamField path="memoryId" type="string" required>
  Memory ID returned by the list endpoint.
</ParamField>

### Get the entity graph

`GET /tenants/:id/memories/graph`

Returns the entities and relationships extracted from durable memory. Tenants without active durable memory return an empty graph.

See [Durable memory](/memory/durable-memory) for recall, retention, and knowledge-base isolation behavior.

## Next steps

<CardGroup cols={2}>
  <Card title="Tenancy model" icon="sitemap" href="/developers/concepts/tenancy">
    Design secure customer and environment boundaries.
  </Card>

  <Card title="Billing & usage" icon="credit-card" href="/developers/api/billing">
    Inspect credits and usage for each tenant.
  </Card>

  <Card title="Knowledge bases" icon="database" href="/developers/api/knowledge-bases">
    Create content containers inside a tenant.
  </Card>
</CardGroup>