API Documentation — OC Intelligence

Authentication

All API requests require an API key passed in the X-API-Key header. Generate your key from the Account page.

# Include your API key in every request curl https://intelligence-proxy.damian-hastie.workers.dev/api/v1/status \ -H "X-API-Key: oci_your_api_key_here"

Keys look like oci_ followed by 64 hex characters. Keep your key secret — never expose it in client-side code.

Rate Limits

Limits are per API key per calendar day, resetting at midnight UTC. Your remaining requests are returned in every response under meta.requests_remaining.

Investigator — 100 / day

Professional — 500 / day

Enterprise — 2,000 / day

When you exceed your limit the API returns HTTP 429 with a JSON error body.

Response Format

All responses are JSON with a consistent envelope:

      
{
  "success": true,
  "data": [ /* array of results */ ],
  "total": 142,
  "limit": 50,
  "meta": {
    "tier": "enterprise",
    "requests_today": 12,
    "requests_remaining": 1988,
    "rate_limit": 2000
  }
}

Endpoints

GET /api/v1/status Check API status and key info

curl /api/v1/status -H "X-API-Key: oci_..."

GET /api/v1/contracts Search awarded contracts

Search across Contracts Finder (400k+) and PCS Scotland (25k+). Returns awarded contracts matching your query.

Query Parameters

Parameter	Type	Required	Description
q	string	optional	Keyword search across title, buyer and supplier
source	string	optional	`cf`, `pcs`, or `cf,pcs` (default: both)
date_from	date	optional	Published date from (YYYY-MM-DD)
date_to	date	optional	Published date to (YYYY-MM-DD)
cpv	string	optional	CPV code prefix e.g. `72` for IT Services
min_value	number	optional	Minimum contract value in GBP
limit	integer	optional	Results per page (default 50, max 200)
offset	integer	optional	Pagination offset (default 0)

curl "/api/v1/contracts?q=fire+safety&source=cf,pcs&min_value=50000&limit=20" \ -H "X-API-Key: oci_..."

GET /api/v1/buyers/{name} Buyer intelligence profile

Returns a buyer profile with spending statistics and recent awarded contracts. URL-encode the buyer name.

curl "/api/v1/buyers/NHS%20Greater%20Glasgow" \ -H "X-API-Key: oci_..."

Response fields

Field	Description
profile.total_spend	Total awarded contract value (GBP)
profile.contract_count	Total number of awarded contracts
profile.top_suppliers	Most frequently awarded suppliers
recent_contracts	Up to 20 most recent awards

GET /api/v1/suppliers/{name} Supplier intelligence profile

Returns a supplier profile with contract history, win rates and buyer relationships. URL-encode the supplier name.

curl "/api/v1/suppliers/Serco%20Group%20PLC" \ -H "X-API-Key: oci_..."

GET /api/v1/renewals Contracts approaching expiry

Returns contracts estimated or confirmed to be expiring within the specified window. Ideal for identifying re-tender opportunities programmatically.

Query Parameters

Parameter	Type	Required	Description
window_months	integer	optional	Look-ahead window in months (default 12, max 36)
source	string	optional	`cf`, `pcs`, or both (default)
cpv	string	optional	CPV code prefix
min_value	number	optional	Minimum contract value in GBP
limit	integer	optional	Results (default 50, max 200)

Urgency values

Results include an urgency field: critical (≤90 days), soon (≤180 days), upcoming (≤365 days), pipeline (>365 days).

curl "/api/v1/renewals?window_months=6&cpv=72&min_value=100000" \ -H "X-API-Key: oci_..."

Error Codes

Status	Meaning
401	Missing or invalid API key
404	Unknown endpoint
429	Rate limit exceeded — resets midnight UTC
500	Internal server error

Quick Start (JavaScript)

      
const OCI_KEY = 'oci_your_key_here';
const BASE = 'https://intelligence-proxy.damian-hastie.workers.dev';

// Search contracts
async function searchContracts(keyword) {
  const res = await fetch(
    `${BASE}/api/v1/contracts?q=${encodeURIComponent(keyword)}&limit=20`,
    { headers: { 'X-API-Key': OCI_KEY } }
  );
  const { data, meta } = await res.json();
  console.log(`Found ${data.length} contracts, ${meta.requests_remaining} requests remaining`);
  return data;
}

// Get renewals expiring in 6 months
async function getUrgentRenewals() {
  const res = await fetch(
    `${BASE}/api/v1/renewals?window_months=6&min_value=50000`,
    { headers: { 'X-API-Key': OCI_KEY } }
  );
  const { data } = await res.json();
  return data.filter(r => r.urgency === 'critical');
}

Ready to get started? Generate your API key →

OC Intelligence API

Authentication

Rate Limits

Response Format

Endpoints

Query Parameters

Response fields

Query Parameters

Urgency values

Error Codes

Quick Start (JavaScript)