View as markdown
Endpoints · Universes

Create a universe

POSThttps://api.tickerbot.io/v2/universes

Create a named ticker list owned by your account.

Body parameters

stringrequired

Human-readable label, up to 80 characters. Display-only — never used to reference the universe.

string[]required

Ticker symbols, up to 10,000. Validated against the active universe. [] is accepted — a shell universe you can fill later via PATCH.

string

Optional slug — becomes the universe's permanent handle everywhere (?universe=, subscribe universe, CRUD path). Pattern ^[a-z][a-z0-9_]{0,62}$ — starts with a lowercase letter, then lowercase letters/digits/underscore, 63 chars max; the value is trimmed and lowercased before validation. top_10 and top_100 are reserved for system universes and rejected with 400. Must be unique within your account. Generated (u_…) if omitted.

string

Free-form notes, up to 500 characters. Stored as "" when omitted.

Headers

string

Optional unique string (≤255 chars). A retry carrying the same key within 24h replays the original response (Idempotency-Replayed: true header) instead of creating a duplicate; a concurrent duplicate gets 409 idempotency_in_flight; reusing a key for a *different* request (another method or path) gets 422 idempotency_key_reused. 5xx responses are not stored — those retries re-execute.

Status codes

201
Universe created. Returns the full universe doc.
400
bad_request for malformed tickers or oversized universe; unknown_tickers (with a disallowed array) when symbols aren't in our universe.
400
too_many_universes — the account-level ceiling of 1,000 universes, a flat anti-abuse guard identical for every account.
409
slug_taken when id collides with one of your existing universes; or idempotency_in_flight — a concurrent request with the same Idempotency-Key is still executing.
422
idempotency_key_reused — the Idempotency-Key was already used for a *different* request (another method or path). Use a fresh key per distinct request.

Notes

  • Body: { id?, name, description?, tickers }. The id (slug) is the universe's only handle — it is what you pass as ?universe= on queries and universe on subscribes. name is a display label and never references the universe.
  • Pick a memorable id: omit it and a random slug (u_…) is generated, which you will be referencing forever.