OQRO for developers and agents

Ways to connect

• REST API

  Read-only JSON at https://oqro.io/api/v1: insider trades, Congress trades, 13F fund moves, contracts, lobbying, prices, a screener. One personal key.

• OpenAPI description

  The same API as an OpenAPI 3.1 file, with the typed error schema and the rate-limit headers, for generators and agent frameworks.

• MCP server

  Remote server over Streamable HTTP at https://oqro.io/api/mcp, with read-only tools and OAuth sign-in. Its card is at https://oqro.io/.well-known/mcp.

• Command-line tool

  npm install -g oqro, then oqro insiders NVDA --side sell. JSON on stdout, for scripts and agents with a shell.

• llms.txt

  What OQRO covers, when to use it, and the pages worth reading, written for AI assistants.

• Markdown for every page

  Any public page returns Markdown when asked with Accept: text/markdown.

Quickstart

1. Start the 3-day free trial of OQRO Pro (the API is part of it), or log in.
2. Open API keys, name a key and copy it. It is shown once.
3. Send it as a bearer token.

export OQRO_API_KEY=oqro_...

curl "https://oqro.io/api/v1/insider-trades?ticker=NVDA&side=sell&days=180&limit=5" \
  -H "Authorization: Bearer $OQRO_API_KEY"

# or with the command-line tool
npx oqro insiders NVDA --side sell --days 180 --limit 5

There is no separate sandbox: the API is read-only and returns the same public disclosures as production, so a test call cannot change or break anything. The free trial gives a working key.

Rate limits

Each key may make 60 requests a minute and 5,000 a day. Every answer, errors included, carries the standard RateLimit headers, so a client can throttle itself before it is refused; a refusal is HTTP 429 with Retry-After.

RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 38                 # seconds until the minute window restarts
RateLimit-Policy: 60;w=60, 5000;w=86400
Retry-After: 38                     # on a 429 only

The older X-RateLimit-* names are sent as well. Tell us if you need a higher quota.

Errors

Every 4xx and 5xx answer has one JSON shape, described in the OpenAPI file as the Error schema. Branch on code; the message is for people and can change wording.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 38

{ "error": { "code": "rate_limited", "message": "Rate limit reached (60 requests a minute per key). Retry in 38 seconds." } }

401

missing_api_key

401

invalid_api_key

402

subscription_required

429

rate_limited

400

invalid_parameter

404

ticker_not_covered

404

not_found

503

data_unavailable

503

service_unavailable

500

internal_error

Versioning and deprecation

• The version is in the address: /api/v1. Every answer carries API-Version: 1.
• Inside a version we only add: new endpoints, new optional parameters, new fields in a response. A client must ignore fields it does not know.
• Removing or renaming anything, or changing what a field means, happens in a new version (/api/v2), never in place.
• A version is announced as deprecated at least 180 days before it is switched off. From the announcement its answers carry Deprecation and Sunset headers (RFC 9745 and RFC 8594) and a Link header with rel="deprecation" pointing here, and the change is posted on this page.
• No version is deprecated today.

For AI agents

Read llms.txt first: it says what OQRO covers and when to reach for it. To call OQRO as tools, connect the MCP server; to call it from code, use the REST API or the command-line tool above.

Every public page can be read as Markdown. Ask for it with the Accept header; the same address still answers HTML to a browser.

curl -H "Accept: text/markdown" https://oqro.io/insiders

HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: Accept

A page that does not exist answers 404 with a short Markdown body that points to llms.txt, the sitemap and this page.