# Sentra

> Sentra is the organizational memory system: it joins meetings, builds a memory of people / projects / decisions, and exposes that memory through a programmatic API and application.

Customer-facing endpoints are versioned under `https://api.sentra.app/external/v1/`. Every call is authenticated with the caller's personal API key, passed as `Authorization: Bearer sk_sentra_…`. Users generate keys from Settings → API Access in the Sentra web or desktop app and the raw value is shown only once.

## Common pitfalls (read first)

- The version namespace is `/external/v1`, **not** `/v1`. There is no endpoint at `/v1/users`, `/v1/me`, or `/v1/anything`.
- The OpenAPI spec lives at `/external/v1/openapi.json`. The canonical `/openapi.json` location on the host 301s here, so either works.
- `GET /` and `GET /external/v1` both return a small JSON discovery descriptor (auth header, spec URL, endpoint list). Use them when probing for capabilities.
- Sentra does not expose a "current user" / `/me` endpoint on the API-key surface. The closest signal is the user implied by the meetings and entities each key can read.

## Docs

- [OpenAPI specification](https://api.sentra.app/external/v1/openapi.json): Machine-readable OpenAPI 3 contract covering every public endpoint. Filtered to exclude internal admin and dashboard routes. Also reachable via the 301 from `https://api.sentra.app/openapi.json`.
- [Interactive API reference](https://www.sentra.app/docs/api): Human-friendly browsable docs (Scalar) rendered over the same spec.
- [API discovery descriptor](https://api.sentra.app/): Tiny JSON summary of base URL, auth header, and endpoints. Same payload served at `https://api.sentra.app/external/v1`.
- [Generating a key](https://www.sentra.app/docs/api#section/Authentication): How an end user provisions, rotates, or revokes their personal API key.

## Endpoints

- `GET /external/v1/meetings`: List meetings the caller can read, paginated. Admins see all org meetings except `PRIVATE` ones they did not attend; non-admins see only meetings they attended. Supports `search`, `limit`, `offset`.
- `GET /external/v1/meetings/{meeting_id}`: Full meeting payload including summary, transcript, and attendees. Returns `409 Conflict` with `{"status": "processing"}` when the transcript artefact is not yet uploaded. Returns `502 Bad Gateway` when the storage backend is unreachable.
- `GET /external/v1/entities`: List entities (people / projects / topics) Sentra has extracted from the caller's accessible meetings. Supports `search`, `limit`, `offset`, and `type` filtering.
- `GET /external/v1/entities/{entity_id}/chunks`: Paginated fact chunks for a given entity. Each chunk cites the source meeting or file. Defaults to 10 per page, capped at 100.

## Authentication

Every endpoint requires the caller's API key, passed as a standard bearer token:

```bash
curl https://api.sentra.app/external/v1/meetings?limit=25 \
  -H "Authorization: Bearer sk_sentra_REPLACE_WITH_YOUR_KEY"
```

Keys carry the `sk_sentra_` brand prefix and inherit the owning user's organization scope and meeting visibility. Sentra never returns the raw key value after creation — store it in a secrets manager at issue time.

## Rate limits

Per-key, evaluated against a hashed key identifier. Read endpoints under `/external/v1/*` allow 120 requests/minute. Exceeded limits return `429 Too Many Requests` with a `Retry-After` header.

## Errors

- `401 Unauthorized`: missing, invalid, expired, or revoked key.
- `404 Not Found`: the caller cannot see the requested resource (the response is identical whether the resource does not exist or the caller lacks visibility — no enumeration leak).
- `409 Conflict`: a meeting's transcript is still processing; safe to retry with backoff.
- `429 Too Many Requests`: per-key rate limit exceeded.
- `502 Bad Gateway`: upstream storage is temporarily unreachable; safe to retry with backoff.

## Optional

- [Status page](https://status.sentra.app): Real-time API availability.
- [Contact](https://www.sentra.app/contact): Support, integration questions, security disclosures.