# Oro Intel REST API

Base URL `https://api.oro-intel.com`. Every request needs an
`Authorization: Bearer oro_...` header. The full machine-readable schema is the
OpenAPI 3.1 spec at `https://api.oro-intel.com/openapi.json`.

## Credit costs

| 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 |

## The flagship: company profile

`GET /v1/companies/{company_number}/profile` returns **everything under a company in
one call** — the core record plus every public contract it has won — for **12
credits**, cheaper than buying those layers separately. It's the right default when you
need a full picture. The Companies House registration number, where we hold it, is part
of the core record.

## Response shape

Every metered response echoes what it cost and what you have left:

```json
{
  "core": { "...": "..." },
  "contracts": { "contract_count": 132, "items": [ "..." ] },
  "credits_charged": 12,
  "credits_remaining": 233
}
```

You are charged on success only. Pass an `Idempotency-Key` header so retries never
double-bill.