# Oro Intel — full documentation for agents

Oro Intel is the UK public-procurement data layer for AI agents. Notices, live tenders,
buyers and suppliers are available over a metered REST API and an MCP server. Browsing
the data on the web is free; the structured data layer is metered in prepaid credits.

- Get an API key: https://app.oro-intel.com/dashboard/developers
- REST base: https://api.oro-intel.com/v1/ — OpenAPI 3.1: https://api.oro-intel.com/openapi.json
- MCP (streamable HTTP): https://api.oro-intel.com/mcp/  (keep the trailing slash)

===============================================================================
# Overview — authentication & credits
===============================================================================

Create an API key in the web app (Developers, or Settings → Billing → API keys). The
full key is shown once. Send it as a bearer token:

    Authorization: Bearer oro_xxxxxxxxxxxx

New accounts get 250 free credits. 1 credit = £0.01 net. Every metered response includes
`credits_charged` and `credits_remaining`. You are charged on SUCCESS ONLY — a lookup
that returns nothing is not billed. Pass an `Idempotency-Key` header so retries never
double-bill.

When you run out, you get a 402-style body:

    {
      "error": "insufficient_credits",
      "action": "company_profile",
      "required": 12,
      "balance": 4,
      "top_up_url": "https://app.oro-intel.com/dashboard/settings/billing"
    }

===============================================================================
# REST API — endpoints & credit costs
===============================================================================

Base URL https://api.oro-intel.com. Every request needs Authorization: Bearer oro_...

| Action | REST | MCP tool | Credits |
|---|---|---|---|
| Search notices | GET /v1/notices/search | oro_search_notices | 2 |
| Search live tenders | GET /v1/tenders/search | oro_search_tenders | 2 |
| Look up a contract | GET /v1/contracts/{id} | oro_lookup_contract | 5 |
| Contract documents | GET /v1/contracts/{id}/documents | oro_contract_documents | 10 |
| Look up a company | GET /v1/companies/{n} or /search | oro_lookup_company | 5 |
| Company contracts won | GET /v1/companies/{n}/contracts | oro_company_contracts | 10 |
| Full company profile | GET /v1/companies/{n}/profile | oro_company_profile | 12 |
| Look up a buyer | GET /v1/buyers/{id} | oro_lookup_buyer | 5 |
| Buyer contracts issued | GET /v1/buyers/{id}/contracts | oro_buyer_contracts | 10 |
| Buyer profile | GET /v1/buyers/{id}/profile | oro_buyer_profile | 20 |
| Look up a framework | GET /v1/frameworks/{id} | oro_lookup_framework | 5 |
| Bulk export | POST /v1/exports | oro_bulk_export | 100 / 1,000 rows |
| Get balance | GET /v1/balance | oro_get_balance | free |

Flagship: GET /v1/companies/{company_number}/profile returns the core record plus every
public contract a company has won in one call, for 12 credits. Response echoes
credits_charged + credits_remaining.

===============================================================================
# MCP server
===============================================================================

Endpoint: https://api.oro-intel.com/mcp/ (trailing slash required). Same bearer key.

Add to Claude Code:

    claude mcp add --transport http oro-intel https://api.oro-intel.com/mcp/ \
      --header "Authorization: Bearer oro_YOUR_KEY"

Or add directly to ~/.claude.json under mcpServers:

    "oro-intel": {
      "type": "http",
      "url": "https://api.oro-intel.com/mcp/",
      "headers": { "Authorization": "Bearer oro_YOUR_KEY" }
    }

Tools mirror the REST endpoints one-to-one with the same credit costs:
oro_search_notices, oro_search_tenders, oro_lookup_contract, oro_contract_documents,
oro_lookup_company, oro_company_contracts, oro_company_profile, oro_lookup_buyer,
oro_buyer_contracts, oro_buyer_profile, oro_lookup_framework, oro_bulk_export,
oro_get_balance.

===============================================================================
# Examples
===============================================================================

Company by name -> full profile:

    # 1. Find the company (5 credits)
    curl -s "https://api.oro-intel.com/v1/companies/search?name=Capita" \
      -H "Authorization: Bearer $ORO_KEY"
    # -> { "id": "...", "name": "CAPITA PLC", "companies_house_number": "02081330",
    #      "credits_charged": 5, "credits_remaining": 245 }

    # 2. Pull the full profile (12 credits)
    curl -s "https://api.oro-intel.com/v1/companies/02081330/profile" \
      -H "Authorization: Bearer $ORO_KEY"
    # -> { "core": {...}, "contracts": { "contract_count": 132, "items": [...] },
    #      "credits_charged": 12, "credits_remaining": 233 }

From MCP: call oro_company_profile with { "company_number": "02081330" } or
{ "name": "Capita" }.

Tips: send a stable Idempotency-Key per request; check credits_remaining and top up
before zero; prefer the profile bundle over separate lookups when you need everything.

===============================================================================
Oro Intel Ltd · https://oro-intel.com · william@oro-intel.com · United Kingdom