Get started
Authentication and keys
Every key belongs to an account. An account holds up to 10 active keys, which share its plan and its daily credits. Name a key for the server or app that uses it, rotate it without downtime, and revoke it the moment it leaks.
Send the key in a header
Use either header. Both accept the same creo_ key.
curl https://itscreo.com/v1/account -H "x-api-key: $CREO_KEY" curl https://itscreo.com/v1/account -H "Authorization: Bearer $CREO_KEY"
Keys in the URL are refused with 400 KEY_IN_QUERY, because URLs end up in logs,
proxies and browser history.
Which endpoints need a key
- No key: creating an account's first key, plans, status, account recovery, and the demo tickers (up to 20 calls a day per IP).
- Key required: scoring your own holdings, and everything under
/v1/account.
Store it once
Creo keeps only a SHA-256 hash of each key and shows the secret once, when it is created.
Afterwards you see its prefix, such as creo_Xk3a9Qf, which is enough to tell keys
apart in a list. Keep the secret in a secret store or an environment variable such as
CREO_KEY. Each IP address can create 5 new accounts a day.
Create an account and its first key
Pass an optional name, and an optional email to use for account recovery.
POST/v1/keys
Mint a free API key No key needed
Returns a new key once; Creo stores only its hash. No auth needed. Limited to 5 keys per IP per UTC day, so reuse your key (for example from a CREO_KEY environment variable) instead of minting per run.
Request body
Example
curl -X POST https://itscreo.com/v1/keys \
-H "content-type: application/json" \
-d '{}'Responses
- 201Successful Response
IssuedKey - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 429RATE_LIMITED: 5 new keys per IP per day
Error
Response fields
keystringrequiredThe secret. Shown once; Creo stores only a hash.
idstringrequirednamestringnullablekey_prefixstringrequiredplanstringrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredcreated_atdatetimerequiredManage keys
List keys to see each one's name, prefix, created and last-used times, and state:
active, expiring (inside a rotation overlap), expired
or revoked. Any active key on the account can manage the others.
GET/v1/account/keys
List this account's keys Requires a key
Every key on the account with its prefix, created and last-used times and state.
Example
curl https://itscreo.com/v1/account/keys \ -H "x-api-key: $CREO_KEY"
Responses
- 200Successful Response
KeyList - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error
Response fields
keysarray of KeyInforequiredChild fields
idstringrequirednamestringrequiredkey_prefixstringrequiredstateenumrequiredOne of active, expiring, expired, revoked
created_atdatetimerequiredlast_used_atdatetimerequiredexpires_atdatetimerequiredSet while a rotated key overlaps with its replacement.
revoked_atdatetimerequiredcurrentbooleanrequiredTrue for the key that made this request.
max_active_keysintegerDefault 10
POST/v1/account/keys
Create another key on this account Requires a key
Shares the account's plan and daily credits. The secret is returned once.
Request body
Example
curl -X POST https://itscreo.com/v1/account/keys \
-H "x-api-key: $CREO_KEY" \
-H "content-type: application/json" \
-d '{}'Responses
- 201Successful Response
IssuedKey - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error - 409KEY_LIMIT: 10 active keys, or LAST_KEY
Error
Response fields
keystringrequiredThe secret. Shown once; Creo stores only a hash.
idstringrequirednamestringnullablekey_prefixstringrequiredplanstringrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredcreated_atdatetimerequiredPOST/v1/account/keys/{key_id}/rotate
Rotate a key, optionally keeping the old one working for a while Requires a key
Issues a replacement with the same name. With expires_in_hours the old key keeps working until then; with 0 (the default) it stops immediately.
path parameter key_id:
Request body
Example
curl -X POST https://itscreo.com/v1/account/keys/{key_id}/rotate \
-H "x-api-key: $CREO_KEY" \
-H "content-type: application/json" \
-d '{}'Responses
- 201Successful Response
RotatedKey - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error - 404KEY_NOT_FOUND: not a key on this account
Error
Response fields
new_keyIssuedKeyrequiredChild fields
keystringrequiredThe secret. Shown once; Creo stores only a hash.
idstringrequirednamestringnullablekey_prefixstringrequiredplanstringrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredcreated_atdatetimerequiredold_keyKeyInforequiredChild fields
idstringrequirednamestringrequiredkey_prefixstringrequiredstateenumrequiredOne of active, expiring, expired, revoked
created_atdatetimerequiredlast_used_atdatetimerequiredexpires_atdatetimerequiredSet while a rotated key overlaps with its replacement.
revoked_atdatetimerequiredcurrentbooleanrequiredTrue for the key that made this request.
DELETE/v1/account/keys/{key_id}
Revoke a key Requires a key
Stops the key at once. The account's last active key cannot be revoked.
path parameter key_id:
Example
curl -X DELETE https://itscreo.com/v1/account/keys/{key_id} \
-H "x-api-key: $CREO_KEY"Responses
- 200Successful Response
KeyInfo - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error - 404KEY_NOT_FOUND: not a key on this account
Error - 409KEY_LIMIT: 10 active keys, or LAST_KEY
Error
Response fields
idstringrequirednamestringrequiredkey_prefixstringrequiredstateenumrequiredOne of active, expiring, expired, revoked
created_atdatetimerequiredlast_used_atdatetimerequiredexpires_atdatetimerequiredSet while a rotated key overlaps with its replacement.
revoked_atdatetimerequiredcurrentbooleanrequiredTrue for the key that made this request.
Rotating without downtime
Rotation issues a replacement with the same name. Set expires_in_hours (up to 168)
to keep the old key working while you deploy the new one; it stops at that time with no further
action. With 0, the default, the old key stops at once. An expired or revoked key
cannot be rotated again to extend its life.
curl -X POST https://itscreo.com/v1/account/keys/$KEY_ID/rotate \
-H "x-api-key: $CREO_KEY" -H "content-type: application/json" \
-d '{"expires_in_hours": 24}'
Revoking
Revoking stops a key immediately. The account's last active key cannot be revoked
(409 LAST_KEY), so an account never locks itself out: create or rotate to a new key
first.
Plan, usage and the request log
Reading the account is free and never charged. Usage covers the last 30 UTC days: calls
attempted and credits charged per day, for the whole account or one key with
?key_id=. The request log keeps every keyed, scored call (time, route, status,
credits and request ID) for 30 days, up to 1,000 per account. Every response carries its request
ID in the X-Request-Id header; quote it when you contact support.
GET/v1/account
Account Requires a key
Example
curl https://itscreo.com/v1/account \ -H "x-api-key: $CREO_KEY"
Responses
- 200Successful Response
AccountStatus - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error
Response fields
account_idstringrequiredkey_idstringrequiredkey_namestringrequiredkey_prefixstringrequiredrecovery_emailstringrequiredrecovery_availablebooleanrequiredFalse while Creo has no outgoing email configured.
planPlanrequiredChild fields
idstringrequirednamestringrequiredmonthly_usdintegerrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredsummarystringrequiredfeaturesarray of PlanFeatureChild fields
textstringrequiredenforced_byarray of stringrequiredHow Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).
subscription_planstringrequiredsubscription_statusstringrequiredcurrent_period_enddatetimerequiredcancel_at_period_endbooleanrequiredcan_manage_billingbooleanrequiredcalls_used_todayintegerrequiredreset_atdatetimerequiredGET/v1/account/usage
Daily calls and credits for 30 days, and recent requests Requires a key
Account-wide by default; pass key_id for one key. Free, never charged.
query parameter key_id:
Example
curl https://itscreo.com/v1/account/usage \ -H "x-api-key: $CREO_KEY"
Responses
- 200Successful Response
AccountUsage - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error
Response fields
key_idstringrequiredThe key filtered on, or null for every key.
daysarray of UsageDayrequiredThe last 30 UTC days, oldest first.
Child fields
daydaterequiredcallsintegerrequiredScored calls attempted, including rate-limited ones.
creditsintegerrequiredCredits charged after refunds.
requestsarray of LoggedRequestrequiredThe 100 most recent scored calls.
Child fields
atdatetimerequiredkey_idstringrequiredkey_prefixstringrequiredmethodstringrequiredroutestringrequiredstatusintegerrequiredcreditsintegerrequiredrequest_idstringrequiredlog_retentionstringDefault "Scored calls from the last 30 days, up to 1,000 per account."
Account recovery
Add a recovery email to the account. If you lose every key, request a link at
/account; it works once, for 30 minutes, and mints a new key on the same
account, with the same plan and billing. Your other keys keep working, so revoke any you have
lost afterwards. The recovery request always answers 202, whether or not the email
matches an account, so it cannot reveal who holds one. The email is used for nothing else.
Recovery email is optional and off by default. While it is off, /v1/account reports
recovery_available: false and a recovery request returns
503 RECOVERY_UNAVAILABLE.
Keep a backup key
Any active key on an account can manage every other key, so a second key is a complete recovery
path that works today. Create one named Backup key, store it in your password
manager, and use it only to sign in at /account and rotate or revoke the
rest if you lose your working key.
PUT/v1/account/recovery-email
Set or remove the account's recovery email Requires a key
Request body
emailstringrequiredWhere recovery links go; null removes it.
Example
curl -X PUT https://itscreo.com/v1/account/recovery-email \ -H "x-api-key: $CREO_KEY"
Responses
- 200Successful Response
AccountStatus - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error
Response fields
account_idstringrequiredkey_idstringrequiredkey_namestringrequiredkey_prefixstringrequiredrecovery_emailstringrequiredrecovery_availablebooleanrequiredFalse while Creo has no outgoing email configured.
planPlanrequiredChild fields
idstringrequirednamestringrequiredmonthly_usdintegerrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredsummarystringrequiredfeaturesarray of PlanFeatureChild fields
textstringrequiredenforced_byarray of stringrequiredHow Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).
subscription_planstringrequiredsubscription_statusstringrequiredcurrent_period_enddatetimerequiredcancel_at_period_endbooleanrequiredcan_manage_billingbooleanrequiredcalls_used_todayintegerrequiredreset_atdatetimerequiredPUT/v1/account/recovery-email
Set or remove the account's recovery email Requires a key
Request body
emailstringrequiredWhere recovery links go; null removes it.
Example
curl -X PUT https://itscreo.com/v1/account/recovery-email \ -H "x-api-key: $CREO_KEY"
Responses
- 200Successful Response
AccountStatus - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 401AUTHENTICATION_REQUIRED: missing or invalid key
Error
Response fields
account_idstringrequiredkey_idstringrequiredkey_namestringrequiredkey_prefixstringrequiredrecovery_emailstringrequiredrecovery_availablebooleanrequiredFalse while Creo has no outgoing email configured.
planPlanrequiredChild fields
idstringrequirednamestringrequiredmonthly_usdintegerrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredsummarystringrequiredfeaturesarray of PlanFeatureChild fields
textstringrequiredenforced_byarray of stringrequiredHow Creo enforces it: gate:<feature> (a plan check on the route), limit:daily_call_limit or limit:max_positions, includes:<plan>, included (every key gets it) or terms (the license, not a technical limit).
subscription_planstringrequiredsubscription_statusstringrequiredcurrent_period_enddatetimerequiredcancel_at_period_endbooleanrequiredcan_manage_billingbooleanrequiredcalls_used_todayintegerrequiredreset_atdatetimerequiredPOST/v1/account/recover
Email a recovery link No key needed
No key needed. Always 202 when recovery is on, whether or not the email matches an account, so it cannot reveal who holds one.
Request body
emailstringrequiredExample
curl -X POST https://itscreo.com/v1/account/recover \
-H "content-type: application/json" \
-d '{}'Responses
- 202Successful Response
- 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 429RATE_LIMITED: 5 requests per IP per day
Error - 503RECOVERY_UNAVAILABLE: outgoing email is off
Error
POST/v1/account/recover/redeem
Mint a new key from a recovery link No key needed
Single use, valid 30 minutes. Existing keys keep working; revoke lost ones after.
Request body
tokenstringrequiredThe token from the link.
Example
curl -X POST https://itscreo.com/v1/account/recover/redeem \
-H "content-type: application/json" \
-d '{}'Responses
- 201Successful Response
IssuedKey - 422INVALID_REQUEST, or a typed failure such as PRICES_REQUIRED, QUANTITY_NEEDS_VALUE or POSITION_LIMIT. Not charged.
Error - 400KEY_IN_QUERY: send the key in a header, not the URL
Error - 410RECOVERY_LINK_INVALID: expired or already used
Error
Response fields
keystringrequiredThe secret. Shown once; Creo stores only a hash.
idstringrequirednamestringnullablekey_prefixstringrequiredplanstringrequireddaily_call_limitintegerrequiredmax_positionsintegerrequiredcreated_atdatetimerequired