Developer Docs

Build with the Flowstates platform

Authenticate with an API key, create branded URL short links, generate one-time passwords and validate them. More endpoints will be added as the platform expands.

Quickstart Request an API key

Quickstart Authentication URL Shortener API OTP API Errors & gaps Machine-readable assets

Quickstart

All endpoints are served from a single base URL. Every request needs your API key in the x-api-key header and JSON requests use Content-Type: application/json.

Base URL

https://cpt.cx

Required headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Create a short link

curl -X POST "https://cpt.cx/shortlink/public-generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BBC News",
    "url": "https://www.bbc.com/news",
    "domain": "cpt.cx",
    "tags": ["News", "BBC"]
  }'

Authentication

Every public endpoint is authenticated with an API key sent in the x-api-key header. Keys are scoped to your account, the domains registered against it and the providers configured for your channels. Treat keys as secrets — never embed them in client-side code.

Required header

x-api-key: YOUR_API_KEY

URL short links API

Create branded URL short links on any domain registered to your account. Use the single endpoint for one link, or the batch endpoint to generate many in one request — ideal for SMS, RCS, WhatsApp and email campaigns.

POST/shortlink/public-generate

Create one short link

Request body

name — string, required
url — string, required, must use http or https
domain — string, required, must be a domain registered to your account
tags — array of strings, optional
username / password — optional, must be supplied as a pair to password-protect the link

Request

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

200 OK

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

Default expiry is 30 days from creation.

POST/shortlink/public-generate-batch

Create URL short links in batch

Send a JSON array of short-link objects. Each item uses the same fields and validation rules as the single-create endpoint. The response contains a summary plus a result for every input item.

Request

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

200 OK

{
  "summary": { "successCount": 2, "failedCount": 0 },
  "results": [
    {
      "name": "BBC News",
      "shortUrl": "https://cpt.cx/RRRRRT",
      "createdDate": "2025-07-02T15:42:05Z",
      "expiryDate":  "2025-08-01T15:42:05Z"
    },
    {
      "name": "Facebook",
      "shortUrl": "https://cpt.cx/RRRRRa",
      "createdDate": "2025-07-02T15:42:05Z",
      "expiryDate":  "2025-08-01T15:42:05Z"
    }
  ]
}

OTP API

Generate one-time passwords for SMS or email delivery and validate them later with the returned otpId. The OTP value is never returned by the API — it is delivered to the recipient and stored only as a hash with a TTL.

POST/otp/generate

Generate an OTP

Request body

channel — required, email or sms
provider — required, the provider configured for that channel on your account (e.g. generic, twilio, sendgrid)
destination — required, email address or E.164 phone number
type — required, numeric or alphanumeric
length — required, between 4 and 12
expiresInSeconds — required, must be greater than 0

Request

{
  "channel": "email",
  "provider": "generic",
  "destination": "test@example.com",
  "type": "alphanumeric",
  "length": 8,
  "expiresInSeconds": 300
}

200 OK

{
  "otpId": "51a6fcc7-efc8-4e69-8bc1-ebb999befb2c",
  "destination": "test@example.com",
  "createdAt": "2025-09-10T14:05:41Z",
  "expiresAt": "2025-09-10T14:10:41Z"
}

POST/otp/validate

Validate an OTP

Send the otpId returned by /otp/generate together with the OTP value the user supplied. A successful validation consumes the OTP — codes are single-use.

Request

{
  "otpId": "c4f8814c-7a9d-4e13-b7d8-d4e66d272611",
  "otp": "z4dGyBPQ"
}

200 OK

{
  "success": true,
  "message": "OTP validated successfully."
}

After repeated failed attempts, validation will return Too many failed attempts. Try again later. until the temporary lock expires.

Errors & known gaps

Validation errors are returned with descriptive messages such as Invalid URL format. or Provider not found for this client and channel.. The following details are not yet documented publicly — treat them as TODOs and contact us if you need a definitive answer for production use:

Auth failure payloads and exact 4xx/5xx response shapes
Rate limits per endpoint and per account
Maximum batch size for short-link creation
Per-item failure structure inside a partially successful batch
Whether short-link expiry can be customised beyond the default 30 days
OTP temporary lock duration after too many failed attempts

Machine-readable assets

Files for AI agents, LLM crawlers, API client generation and technical discovery. Linked from the site's HTML head and robots.txt for reliable discoverability.

openapi.yaml

Machine-readable API definition

/llms.txt

Flowstates LLM overview (site-wide)

/llms-full.txt

Expanded Flowstates company context for LLMs

/docs/llms.txt

Developer/API LLM manifest

/docs/llms-full.txt

Expanded developer/API LLM context

Need an API key or a sandbox?

We will provision keys, register your domains and configure your providers — usually within a day.

Book a Technical Walkthrough Talk to Our Team