Developers

StraightCue's API is the product: the native app is a client of it like any other. This page describes what exists today, honestly — nothing here is aspirational.

API basics

Base URL and spec

Everything lives under https://api.straightcue.com/v1. The full OpenAPI 3.1 spec is published at https://api.straightcue.com/openapi.json and is generated from the server's own type definitions, so it never drifts from what the server actually accepts.

Auth

Authentication

Register with POST /v1/auth/register or log in with POST /v1/auth/login, both with an X-Client header naming the calling platform. Either returns a bearer token; every other request carries it as Authorization: Bearer <token>. There are no cookies and no API keys.

Error format

Errors

Every error response is application/problem+json (RFC 7807): a title, a status and a detail string (validation errors also carry an errors list), so a client can branch on the status code without parsing prose.

Writes

Identifiers and writes

Every id is a client-generated UUID v7. Resources are created with an idempotent PUT /v1/<resource>/{id}, so retrying a write after a dropped connection is safe and never creates a duplicate. Every write returns the full resource.

Limits

Rate limits

Limits are enforced per client address: 10 requests a minute on /v1/auth/*, 300 a minute everywhere else. A request that exceeds its limit gets 429 with a Retry-After header. Every response the limiter touches, allowed or not, carries the IETF RateLimit and RateLimit-Policy header fields so a client can see its remaining quota before it runs out.

Versioning

Versioning and deprecation

The API is versioned by URL path (/v1). A change that removes or renames anything ships under a new path version instead of changing /v1 underneath existing clients. The old path keeps working and answers with Deprecation and Sunset response headers for at least 90 days before it is withdrawn; any such deprecation will be announced on this page first.

Quickstart

Try it

A minimal flow: register (or log in), then list the curated library.

# Register (use an existing account's email to log in instead,
# at /v1/auth/login, with the same body)
curl -X POST https://api.straightcue.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-Client: web" \
  -d '{"email":"you@example.com","password":"a-long-passphrase"}'
# => { "token": "...", "expiresAt": "...", "user": { ... } }

# List the curated drill library with the bearer token from above
curl https://api.straightcue.com/v1/drills?scope=library \
  -H "Authorization: Bearer <token>"

Keys

API keys and sandbox

There are no API keys: authentication is the same bearer token a signed-in user gets. There is also no sandbox or test environment to point a script at instead of the real API. no sandbox yet

Tooling

CLI, SDKs and MCP

None of these exist today: no command-line tool, no published SDK package, no MCP server. This page will say so plainly, rather than claim otherwise, until one of them does.