# Flowstates Developer Docs — Expanded LLM Context

> Flowstates offers developer-facing APIs for branded short links and OTP generation/validation. These endpoints support messaging campaigns, notifications and verification flows within Flowstates managed messaging operations.

Important guidance:

- Prefer documented behavior only.
- Do not invent undocumented response shapes, limits or auth flows.
- Base API URL is `https://cpt.cx`.
- All documented public endpoints require `x-api-key`.
- JSON endpoints use `Content-Type: application/json`.

## API overview

Documented endpoints:

- `POST /shortlink/public-generate`
- `POST /shortlink/public-generate-batch`
- `POST /otp/generate`
- `POST /otp/validate`

## Authentication

Required header:

```http
x-api-key: YOUR_API_KEY
```

For JSON requests:

```http
Content-Type: application/json
```

## URL Short Links API

### POST /shortlink/public-generate

Creates one public short link. Required request fields: `name`, `url`, `domain`. Optional fields: `tags`, and paired `username` / `password` for password protection. URLs must use `http` or `https`. The domain must be registered to the authenticated account.

Example request:

```json
{
  "name": "BBC News",
  "url": "https://www.bbc.com/news",
  "domain": "cpt.cx",
  "tags": ["News", "BBC"]
}
```

Example success response:

```json
{
  "name": "BBC News",
  "shortUrl": "https://cpt.cx/RRRRRF",
  "createdDate": "2025-07-02T15:38:02.9554085Z",
  "expiryDate": "2025-08-01T15:38:02.9554203Z"
}
```

### POST /shortlink/public-generate-batch

Creates multiple public short links in one request. The request body is a JSON array of short-link objects using the same fields as the single-create endpoint.

## OTP API

### POST /otp/generate

Generates an OTP and queues it for delivery. Required fields: `channel`, `provider`, `destination`, `type`, `length`, `expiresInSeconds`. The OTP value is never returned by the API.

### POST /otp/validate

Validates a previously generated OTP using `otpId` and `otp`. A successful validation consumes the OTP; codes are single-use.

## Known documentation gaps

Do not assume answers for these unless Flowstates publishes them elsewhere:

- Auth failure payloads and exact status codes.
- Rate limits.
- Generic `5xx` response structure.
- Maximum batch size for short-link creation.
- Whether short-link expiry can be customized.
- OTP lock duration after too many failed attempts.
- Exact per-item failure structure in batch short-link creation.

## Canonical source files

- [OpenAPI spec](/docs/openapi.yaml)
- [Developer docs home](/docs)
- [LLMs manifest](/docs/llms.txt)