Getting started with API v3

Make your first ROIC API v3 request in a few minutes. You need an API key and an HTTPS client such as curl, Python, or JavaScript. The API returns JSON for data resources and raw bytes for company logos.

Base URL

Send every v3 request to this API host with a path that begins with /v3.0.0.

https://api.roic.ai

For example, the company-profile route is https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL.

Quickstart

Complete these steps to authenticate and retrieve Apple's company profile.

1

Create an account

Sign up for ROIC.ai and open your account to get an API key. The same key works with v2 and v3.

2

Store your API key

Keep the key in an environment variable or secrets manager. Don't commit it to source control or expose it in browser code.

Sign in to see your API key.

3

Make a query-authenticated request

Append ?apikey=<api-key> to the endpoint URL. Query authentication is the quickest way to test a request in your browser or terminal.

bash
curl "https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL?apikey=YOUR_API_KEY"

A successful request returns 200 OK, a Request-Id response header, and one unwrapped company-profile resource.

Use Bearer authentication

Bearer authentication is the recommended method for production applications, server code, and scripts because it keeps your API key out of URLs and logs.

bash
curl "https://api.roic.ai/v3.0.0/company/profile/NASDAQ:AAPL" \
  -H "Authorization: Bearer $ROIC_API_KEY"

Use exactly one authentication method per request. A request that supplies both methods returns 401 Unauthorized, even when both values match.

Response model

Single-resource endpoints return one resource object. List endpoints return a data array with next_page_url and previous_page_url. Errors use a stable envelope with type, code, message, and request_id fields.

Read handle API responses before you build a client. It covers resource shapes, errors, and cursor pagination.

Rate limits and history

Your v2 and v3 requests draw from the same request quota. Each plan sets a per-minute limit and an available history range. Check pricing for current limits.

When you exceed a request limit, the API returns 429 Too Many Requests with a Retry-After header. Cache responses you reuse and retry only after the stated delay. Read handle rate limits for the complete behavior.

Next steps

Continue with the guides and resources that apply to every v3 integration.

Send requests

Use query authentication or the recommended Bearer header.

Search tickers

Resolve company names and symbols to ticker resources.

Handle responses

Read resources, follow pagination, and handle request limits.