---
title: "Mint Retrieval Token"
method: POST
path: "/api/v1/sessions/token"
tags: ["Sessions"]
---

# Mint Retrieval Token

`POST /api/v1/sessions/token`

## Request

- Base URL: `https://api.gemina.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemina.co/api/v1/sessions/token`
- Auth: API key in header `X-API-Key`

Mint a short-lived, signed, query-only retrieval token.

Scope is pinned server-side from the authenticated key: the tenant is the
key's user; an optional ``endUserId`` narrows the session to one end-user.

## Request body

- SessionTokenInDTO
  - `endUserId` string, nullable: Optional end-user scope: the token will only see documents tagged to this end-user. Omit for an admin (whole-account) session.
  - `ttlSeconds` integer, nullable: Requested TTL; clamped server-side to [300, 900] seconds.
  - `extractionIds` string[], nullable: Optional extraction scope: the minted token may only read/verify these document-extraction ids (carried in the signed `xids` claim). Omit for the existing tenant / end-user scoping. Capped at 10; an empty list is rejected rather than silently minting a tenant-wide token.

## Response `200`

Successful Response

- SessionTokenOutDTO
  - `servedAt` string, date-time
  - `servedAtTimestamp` number
  - `createdAt` string, date-time, nullable
  - `createdAtTimestamp` number, nullable
  - `token` string, required
  - `tokenType` string
  - `expiresIn` integer, required
  - `expiresAt` string, date-time, required

## Other responses

- `422`: Validation Error
- `429`: Rate or quota limit exceeded; `errors[0].error_code` says which. Retryable limits (`FILETAG_RATE_LIMIT_EXCEEDED`, burst limits) send a `Retry-After` header: back off and retry after it. `CREDIT_EXHAUSTED` for an account with no active subscription or trial sends no `Retry-After` and is not resolved by waiting: start the free trial (once per account) or choose a plan in the console.

---

[API](https://skmtc.dev/gemina/apis/gemina-api.md) · [All operations](https://skmtc.dev/gemina/apis/gemina-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemina/apis/gemina-api/revisions/152fd3f6f6ec?raw)