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

# Tenant API overview

> HTTP contract of api-tenant — the tenant-scoped gateway in front of every Ntropii tenant cell. Consumed by ui-tenant, ntro-mcp, ntro-cli, and any custom integration that drives a single tenant's workflows.

The Tenant API (`api-tenant`) is a small gateway deployed **per tenant cell**. Every instance is bound to one tenant via `NTRO_TENANT_SLUG` at boot, and every endpoint scopes its api-workspace lookups to that tenant — a request for `/v1/entities` never leaks another tenant's data.

It's the surface the ui-tenant browser app hits directly, and the surface the workspace gateway forwards to when a CLI/MCP call needs a tenant-scoped operation.

## Base URL

In production, the URL is per-tenant — typically `https://<tenant-slug>.tenants.ntropii.com/v1` or a customer-routed equivalent. In local dev:

```
http://localhost:4000/v1
```

All paths below are relative to this base.

## Authentication

`api-tenant` itself **does not enforce HTTP auth** — that's the responsibility of the edge layer in front of the tenant cell (Workspace API gateway, customer ingress, or local dev tooling). The cell trusts whatever reaches it because the cell is, by definition, scoped to one tenant; tenant identity is established at boot, not per-request.

When the workspace gateway forwards calls, it adds `x-ntro-events-key` for the internal events endpoint (`POST /tasks/:taskId/events`). Customer-facing endpoints don't require it.

## Error envelope

All errors come back as a standard NestJS exception filter response:

```json theme={null}
{
  "statusCode": 404,
  "message": "Task abc-123 not found under tenant fundmin",
  "error": "Not Found"
}
```

| Status            | When                                                                    |
| ----------------- | ----------------------------------------------------------------------- |
| `400 Bad Request` | DTO validation failed, illegal subledger transition, malformed `rowId`. |
| `404 Not Found`   | Resource not present (task / row / document) or not under this tenant.  |
| `204 No Content`  | Idempotent disconnect (`DELETE /gl`).                                   |

## Health

```http theme={null}
GET /v1/health
```

Returns `{"status": "ok"}` once the process is up. No tenant binding required — this is the kubelet liveness probe.

## Resources

<CardGroup cols={2}>
  <Card title="Entities" icon="building" href="/api-reference/tenant-api/entities">
    `GET /entities`, per-entity tasks + workflows, `POST /entities/:id/tasks`.
  </Card>

  <Card title="Tasks" icon="list-checks" href="/api-reference/tenant-api/tasks">
    Lifecycle (`/ui`, `/snapshots`, `/action`, `/row-action`), event timeline, files, structured data ingest.
  </Card>

  <Card title="Subledgers" icon="table" href="/api-reference/tenant-api/subledgers">
    Direct cell + reject HTTP endpoints. Prefer workflow signals where possible.
  </Card>

  <Card title="GL" icon="landmark" href="/api-reference/tenant-api/gl">
    `GET /gl/status`, GL connect session, disconnect.
  </Card>
</CardGroup>