RELATIVITY INVEST
Pages:
  [Agent guide](https://www.relativityinvest.ai/agents)
  [Agent guide as Markdown](https://www.relativityinvest.ai/agents.md)
  [API pricing](https://www.relativityinvest.ai/pricing/api)
  [Developer dashboard](https://www.relativityinvest.ai/developer)
Developers:
  [API reference](https://data.relativityinvest.ai/docs/)
  [OpenAPI spec](https://data.relativityinvest.ai/openapi.json)
  [API llms.txt](https://data.relativityinvest.ai/llms.txt)
  [Site llms.txt](https://www.relativityinvest.ai/llms.txt)
  MCP endpoint: https://data.relativityinvest.ai/mcp
  Agent sign-up: POST https://api.relativityinvest.ai/v1/business/agents/sign-up

# For agents: An account, a key and credits. One call, no human.
The Business Data API over REST and MCP. Sign up in one call and start with 100 free credits, no card. After that it is metered per request from a prepaid balance your agent can refill itself.

REST · JSON · Bearer cen_… · 1 credit / request · OpenAPI · MCP

## Endpoints
- Data API: https://data.relativityinvest.ai (metered, bearer key)
- Management API: https://api.relativityinvest.ai (sign-up, keys, credits; never metered)
- MCP server: https://data.relativityinvest.ai/mcp (POST, same bearer key; tools: get_coverage, resolve_company, get_company_briefing, get_company_ownership, get_business_overview, find_similar_companies, compare_company_pair, get_company_movements, get_company_reviews, list_company_reviews, search_media, get_usage)
- Terms: every sign-up, checkout and key-create body carries `"terms_version":"2026-09-21"`, accepting the [API & MCP Terms](https://www.relativityinvest.ai/legal/api-terms) for whoever you act for.
- Envelope: every response is `{ success, data }` or `{ success: false, message, code }`. Keys are snake_case.
- Humans get the same account from [the developer dashboard](https://www.relativityinvest.ai/developer), where keys, credits, usage and the IP allowlist are managed. Subscription tiers with monthly quotas are on [API pricing](https://www.relativityinvest.ai/pricing/api).

## 01. 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.

```bash
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","terms_version":"2026-09-21"}'

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

terms_version is required: it accepts the API & MCP Terms (https://www.relativityinvest.ai/legal/api-terms) on behalf of whoever you act for, and the current value is 2026-09-21. Results are for that account holder's internal use. 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.

## 02. 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.

```bash
curl https://data.relativityinvest.ai/v1/business-overview/companies/0001045810 \
  -H "Authorization: Bearer cen_…"

# X-Credits-Remaining: 99
# → { "data": { "company": {…}, "as_of": { "form_type": "10-K", "filing_date": "2025-02-26" },
#               "profile": {…}, "workforce": {…},
#               "customers": { "count": 50, "has_more": true,
#                              "next": "/v1/business-overview/companies/0001045810/customers" },
#               "competitors": {…}, "suppliers": {…}, "filings": {…}, "risk_factors": {…} } }
```

The business overview returns seven sections in one call — description, workforce, competitors, suppliers, customers, filings, risk factors. Each list section is capped at your plan page size, to a maximum of 150; a capped section sets has_more and names the sub-endpoint that pages it in full. Companies are keyed by SEC CIK or ticker; GET /v1/meta/companies lists the universe. Pay as you go covers every dataset except Company Culture (the company-reviews endpoints), which needs a subscription plan and otherwise returns business.scope_missing. Throttled and rejected requests are free, and a 5xx is refunded. Keep at most 2 requests in flight — more returns business.concurrency_limit.

## 03. Or connect over MCP
The same key works on the MCP server at https://data.relativityinvest.ai/mcp (Streamable HTTP, POST only). Send it as a bearer header; each tool call spends one credit, like a REST request.

```bash
# Claude Code
claude mcp add --transport http relativity-data https://data.relativityinvest.ai/mcp \
  --header "Authorization: Bearer cen_…"

# Cursor — mcp.json
{ "mcpServers": { "relativity-data": {
    "url": "https://data.relativityinvest.ai/mcp",
    "headers": { "Authorization": "Bearer cen_…" } } } }

# Codex — ~/.codex/config.toml
[mcp_servers.relativity-data]
url = "https://data.relativityinvest.ai/mcp"
bearer_token_env_var = "RELATIVITY_API_KEY"
```

Tools: get_coverage, resolve_company, get_company_briefing, get_company_ownership, get_business_overview, find_similar_companies, compare_company_pair, get_company_movements, get_company_reviews, list_company_reviews, search_media, get_usage. The two company-reviews tools need a subscription plan; a pay-as-you-go key does not list them. Keep the key out of committed files — put it in an environment variable and reference that instead.

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

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

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

## 05. 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.

```bash
# 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, "terms_version": "2026-09-21"}'

# 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}'
```

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.

## 06. Manage keys
Issue a key per deployment, rotate on a schedule, revoke without touching the rest.

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

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)
| Status | Code                          | Meaning                                                             |
| ------ | ----------------------------- | ------------------------------------------------------------------- |
| 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)
| Status | Code                                         | Meaning                                                                                       |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 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                         | Sign in and open a pay-as-you-go account from /developer instead.                             |
| 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.                      |

[OPEN THE DEVELOPER DASHBOARD](https://www.relativityinvest.ai/developer)
[SEE API PRICING](https://www.relativityinvest.ai/pricing/api)