> ## 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.

# Entities

> Tenant API entity endpoints — list entities, fetch per-entity tasks (kanban data) and available workflows, start a task run.

Tenant-scoped entity endpoints. Every response is filtered to the tenant this `api-tenant` instance is bound to (via `NTRO_TENANT_SLUG`). Path params are entity **UUIDs**, never slugs — keeping client-identifying strings out of URLs (browser history, screenshots, logs).

## List entities

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

Lists every entity registered against this tenant.

**Response** — `EntitySummary[]`:

```json theme={null}
[
  {
    "id": "0cf95a21-…",
    "tenantId": "11111111-…",
    "slug": "acme-fund-one",
    "name": "Acme Fund One Ltd"
  }
]
```

## List tasks for an entity

```http theme={null}
GET /v1/entities/:entityId/tasks
```

Returns the kanban data for one entity — every task plus an `awaiting` field (the current `display_hint.component`) so the UI can bucket by what each workflow is blocked on. Next-step is fetched per-task in parallel; a missing next-step (e.g. workflow already removed from Temporal) silently drops `awaiting`.

**Path params**

| Param      | Type | Notes                                       |
| ---------- | ---- | ------------------------------------------- |
| `entityId` | UUID | Must belong to this tenant — otherwise 404. |

**Response** — `TaskSummary[]`:

```json theme={null}
[
  {
    "id": "d0b298c2-…",
    "title": "Monthly NAV — 2026-05",
    "status": "IN_PROGRESS",
    "priority": "HIGH",
    "awaiting": "FILE_UPLOAD",
    "entityId": "0cf95a21-…",
    "workflowId": "wf_nav_monthly",
    "createdAt": "2026-05-01T08:00:00Z"
  }
]
```

Terminal tasks (`COMPLETED` / `FAILED`) skip the next-step lookup.

## List available workflows

```http theme={null}
GET /v1/entities/:entityId/workflows
```

Returns workflows the entity can start — tenant-specific workflows plus globally available ones (no `tenantId`). Used by the kanban "Start workflow" dropdown.

**Response**

```json theme={null}
[
  {
    "id": "wf_nav_monthly",
    "name": "nav-monthly",
    "startParams": [
      {
        "key": "period",
        "type": "string",
        "description": "Accounting period (YYYY-MM).",
        "pattern": "^[0-9]{4}-[0-9]{2}$",
        "required": true
      }
    ]
  }
]
```

`startParams` is derived from each workflow's runbook `configSchema.global` block. Each entry carries `key`, `type` (`string` / `number` / `boolean` / `array` / `object`), optional `description` / `pattern` / `enum` / `default`, and `required` (true when the schema field has no `default`). Workflow rows whose runbook lookup fails are still returned, just without `startParams`.

## Create a task

```http theme={null}
POST /v1/entities/:entityId/tasks
```

Starts a workflow run for this entity. Forwards to `api-workspace`'s `POST /workspace/tasks` scoped to this tenant + entity.

**Body**

```json theme={null}
{
  "workflowId": "wf_nav_monthly",
  "context": {
    "period": "2026-05",
    "priority": "HIGH"
  }
}
```

| Field        | Required | Notes                                                                                          |
| ------------ | -------- | ---------------------------------------------------------------------------------------------- |
| `workflowId` | Yes      | Must be one of the IDs returned by `GET /entities/:entityId/workflows`.                        |
| `context`    | No       | Free-form JSON forwarded into the workflow's start payload. Match the runbook's `startParams`. |

**Response** — the created task row from `api-workspace`. Drive it forward with the [Tasks endpoints](/api-reference/tenant-api/tasks).

## Errors

| Status            | When                                                           |
| ----------------- | -------------------------------------------------------------- |
| `404 Not Found`   | `entityId` doesn't belong to this tenant.                      |
| `400 Bad Request` | Missing / malformed body fields, validated by `api-workspace`. |