Create a universe
https://api.tickerbot.io/ v2/ universesSaves a named list of tickers to scope screens and subscriptions.
Body parameters
arrayrequiredTicker symbols, up to 10,000. Validated against the tickers we track. [] is accepted: an empty universe you can fill later via PATCH.
stringrequiredDisplay name, up to 80 characters. Display only: the id is what references the universe.
stringOptional 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.
stringFree-form notes, up to 500 characters. Stored as "" when omitted.
Headers
stringOptional 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.
Returns
as_ofstringServer time this response was assembled (ISO 8601); on an as-of read, the instant you asked for (As-of).
idstringThe slug: the universe's handle in ?universe=.
namestringDisplay label.
descriptionstringFree-form notes; "" when unset.
tickersarrayMembers, after this call.
sizenumberMember count.
kindstringenumAlways custom here: a universe you create or edit is yours.
builtin | A built-in universe, the same for every account: top_10 and top_100. Read-only. |
custom | One of your own universes. |
created_atnumberCreation timestamp (epoch seconds).
updated_atnumberLast modification timestamp (epoch seconds).
effective_atnumberBuilt-in universes only, in epoch seconds; absent on yours.
next_rebalance_atnumberBuilt-in universes only, in epoch seconds; absent on yours.
rebalance_methodstringBuilt-in universes only; absent on yours.
Status codes
| Code | Meaning |
|---|---|
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 tickers we track. |
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, or the same path with a different body). Use a fresh key per distinct request. |