---
title: API
description: Conventions shared by every TALA endpoint — the response envelope, error shapes, pagination, and where the authoritative reference lives.
---

The [API reference](/reference) is generated from the backend's live Swagger document and is the authoritative contract for every operation. These pages cover the conventions the reference does not express.

**[Conventions](/api/conventions)**

Envelope, errors, pagination, scope.

**[Authentication](/api/authentication)**

Token lifecycle, refresh rotation, OAuth exchange.

**[Organizations](/api/organizations)**

Org scoping, roles, invitations.

**[Uploads](/api/uploads)**

The three-step S3 multipart pipeline.

## Surface at a glance

74 routes are declared. 73 appear in the published spec — the seeder controller carries `@ApiExcludeController()`, so its one route is hidden from Swagger.

| Group | Routes | Guards |
| --- | --- | --- |
| Auth | 14 | mostly open; `GET /api/auth/user` requires a bearer token |
| Profile | 3 | `AuthGuard` |
| Collections | 6 | `AuthGuard` + `OrganizationGuard` |
| Assets | 12 | `AuthGuard` + `OrganizationGuard` |
| Upload | 3 | `AuthGuard` + `OrganizationGuard` |
| Organizations | 10 | `AuthGuard`, plus `OrganizationGuard` and `OrganizationRoleGuard` on mutations |
| Projects | 6 | `AuthGuard` + `OrganizationGuard` |
| Tasks | 8 | `AuthGuard` + `OrganizationGuard` |
| Task comments | 4 | `AuthGuard` + `OrganizationGuard` |
| Dashboard | 1 | `AuthGuard` + `OrganizationGuard` |
| Timeline | 4 | `AuthGuard` + `RoleGuard`; three are `ADMIN`-only |
| Plan | 1 | `AuthGuard` |
| Seeder | 1 | `AuthGuard` + `RoleGuard`, `ADMIN` |
| Health | 1 | open, outside the `api` prefix |

:::warning[`@ApiExcludeController` is not access control]
The seeder was once world-reachable and hidden only from Swagger. It now requires an authenticated ADMIN. Hiding an endpoint from the spec hides it from readers, not from callers.
:::