For agents

An account, a key and credits. One call, no human.

The Business Data API over REST, metered per request from a prepaid balance your agent can refill itself.

RESTJSONBearer cen_…1 credit / requestOpenAPIMCP

Data API https://data.relativityinvest.ai — metered, bearer key

Management API https://api.relativityinvest.ai — sign-up, keys, credits; never metered

Reference interactive docs · openapi.json · API llms.txt · site llms.txt

Envelope every response is { success, data } or { success: false, message, code }. Keys are snake_case.

Humans get the same account from /developer, where keys, credits, usage and the IP allowlist are managed. Subscription tiers with monthly quotas are on /pricing/api.

Open an account

One call creates the user, a pay-as-you-go account, its first key and the free credits. The key is returned exactly once. No password needed — omit it and a human reaches the dashboard through password reset. A verification email goes out; data calls work before it is clicked.

Verifying the address pays another 400 credits and lets the saved card be charged unattended later — worth asking your operator to click it. Buying credits through checkout needs no verification. The IP allowlist is off on a pay-as-you-go account, so the key works from wherever the agent runs.

curl -X POST https://api.relativityinvest.ai/v1/business/agents/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@firm.com","name":"Research agent","company_name":"Firm"}'

# → { "data": { "token": "cen_…", "credit_balance": 100, "email_verified": false,
#               "dashboard_access": "password_reset",
#               "verification": { "grants_credits": 400 },
#               "data_api_url": "https://data.relativityinvest.ai", … } }

Read the data

Send the key as a bearer token to the data API. Every request spends one credit; the balance comes back on each response.

Companies are keyed by SEC CIK; GET /v1/meta/companies lists the universe. Throttled and rejected requests are free, and a 5xx is refunded. Keep at most 2 requests in flight — more returns business.concurrency_limit.

curl https://data.relativityinvest.ai/v1/ownership/companies/0000320193 \
  -H "Authorization: Bearer cen_…"

# X-Credits-Remaining: 99

Check yourself

The management API takes the same key. Account, balance, price, and whether a card is saved.

Management routes are never metered, so an empty balance can always be inspected and refilled.

curl https://api.relativityinvest.ai/v1/business/account -H "Authorization: Bearer cen_…"
curl https://api.relativityinvest.ai/v1/business/credits -H "Authorization: Bearer cen_…"

Buy credits, or stop thinking about it

Read X-Credits-Remaining on every response and top up before it reaches zero rather than waiting for the 402. The first purchase goes through a hosted checkout, which saves the card — you can mint that URL immediately after signing up and hand it to your operator. Everything after it is unattended.

Checkout needs no verified email — a person completes it, which is the verification, so an agent can mint that link the moment it signs up. Charging the saved card unattended (top-up, auto-refill) does need it: the link from step 01, clicked once by a human; POST /v1/business/credits/resend-verification sends it again. Unattended charges share a daily spend cap (business.credits_spend_cap when reached); hosted checkout is not capped. Price, bounds, cap and grants all come back from GET /v1/business/credits.

# once — returns a URL for a human to complete (saves the card)
curl -X POST https://api.relativityinvest.ai/v1/business/credits/checkout \
  -H "Authorization: Bearer cen_…" -H "Content-Type: application/json" \
  -d '{"amount_cents": 2000}'

# afterwards — unattended
curl -X POST https://api.relativityinvest.ai/v1/business/credits/top-up \
  -H "Authorization: Bearer cen_…" -H "Content-Type: application/json" \
  -d '{"amount_cents": 2000}'

# → { "data": { "status": "succeeded", "balance": 2099, "credits": 2000 } }

# or set it once and never handle a 402 again
curl -X PUT https://api.relativityinvest.ai/v1/business/credits/auto-refill \
  -H "Authorization: Bearer cen_…" -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold_credits": 1000, "amount_cents": 2500}'

Manage keys

Issue a key per deployment, rotate on a schedule, revoke without touching the rest.

curl -X POST https://api.relativityinvest.ai/v1/business/keys \
  -H "Authorization: Bearer cen_…" -H "Content-Type: application/json" \
  -d '{"name":"backfill"}'

curl https://api.relativityinvest.ai/v1/business/keys -H "Authorization: Bearer cen_…"

curl -X POST https://api.relativityinvest.ai/v1/business/keys/{key_id}/rotate \
  -H "Authorization: Bearer cen_…"

curl -X DELETE https://api.relativityinvest.ai/v1/business/keys/{key_id} \
  -H "Authorization: Bearer cen_…"

Errors

Every failure names its fix.

Branch on code, not on the message. Messages are for logs. The two services name their codes separately, so check which host answered.

Data API https://data.relativityinvest.ai

401

business.key_invalid

Missing, malformed or unknown key.

401

business.key_expired

A rotated key past its grace window. Use the replacement.

401

business.key_revoked

The key was revoked. Issue a new one.

402

business.credits_insufficient

Balance is empty. Top up, then retry.

403

business.scope_missing

That dataset is not on your plan.

403

business.account_suspended

Billing lapsed. Keys work again once the account is active.

429

business.rate_limited

Per-plan request ceiling. Honour Retry-After. Costs nothing.

429

business.concurrency_limit

Too many requests in flight at once. Keep at most 2 open; back off.

Management API https://api.relativityinvest.ai

403

business.credits_email_verification_required

Only top-up needs a verified email. Checkout and data calls do not.

409

business.credits_payment_method_required

No saved card yet — run one checkout, then top-ups work unattended.

409

business.credits_authentication_required

The bank wants interactive auth for this charge. Use checkout.

409

business.credits_payment_processing

Accepted, not settled. Credits land on their own; poll /v1/business/credits.

409

business.email_taken

429

business.credits_spend_cap

Daily unattended spend limit reached. Checkout is not capped; or wait for the window to roll.

429

rate_limit.exceeded

Management-plane limiter (sign-up is 5/hour per IP). Honour Retry-After.