tickerbot.io

Create a universe

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

Saves a named list of tickers to scope screens and subscriptions.

arrayrequired

Ticker symbols, up to 10,000. Validated against the tickers we track. [] is accepted: an empty universe you can fill later via PATCH.

stringrequired

Display name, up to 80 characters. Display only: the id is what references the universe.

string

Optional slug: 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 built-in 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.

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, or the same path with a different body) gets 422 idempotency_key_reused. Only a 2xx is stored: after a 4xx or 5xx, a retry with the same key runs again.

as_ofstring

Server time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).

idstring

The slug: the universe's handle in ?universe=.

namestring

Display label.

descriptionstring

Free-form notes; "" when unset.

tickersarray

Members, after this call.

sizenumber

Member count.

kindstringenum

Always custom here: a universe you create or edit is yours.

builtinA built-in universe, the same for every account: top_10 and top_100. Read-only.
customOne of your own universes.
created_atnumber

Creation timestamp (epoch seconds).

updated_atnumber

Last modification timestamp (epoch seconds).

effective_atnumber

Built-in universes only, in epoch seconds; absent on yours.

next_rebalance_atnumber

Built-in universes only, in epoch seconds; absent on yours.

rebalance_methodstring

Built-in universes only; absent on yours.

CodeMeaning
201Universe created. Returns the full universe doc.
400bad_request for malformed tickers or oversized universe; unknown_tickers (with a disallowed array) when symbols aren't tickers we track.
400too_many_universes: the account-level ceiling of 1,000 universes, a flat anti-abuse guard identical for every account.
409slug_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.
422idempotency_key_reused: the Idempotency-Key was already used for a different request (another method or path, or the same path with a different body). Use a fresh key per distinct request.