Discover EU grant matches, programmatically.

1 · Authenticate

Every request needs a partner API key passed as Authorization: Bearer <key>. Contact Cogrant to get one issued.

2 · Kick off a search

POST /v1/searches is accepted asynchronously; the response returns a job_id you then poll. Two payload shapes are supported — pick one per request.

Existing company — if the company already has a profile in Cogrant:

curl -sS -X POST https://api.cogrant.eu/v1/searches \
  -H 'Authorization: Bearer cog_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sprint-42-client-acme' \
  -d '{"payload": {"company_id": "recABCDEFGHIJKLMN"}}'

New company — the gateway creates the profile on the fly (Organisation Type is set to Private Business) and then runs the search:

curl -sS -X POST https://api.cogrant.eu/v1/searches \
  -H 'Authorization: Bearer cog_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"payload": {
    "company_name": "Acme Bio",
    "company_description": "Fermentation-based protein for the food industry.",
    "country": "Lithuania",
    "website": "https://acme.bio"
  }}'

company_name, company_description, and country are required; website is optional. country must match one of the values Cogrant uses on the Companies → Country field.

3 · Poll for completion

Searches typically finish in 60–120 seconds. Poll every 5–10 seconds until status is done or failed.

curl -sS https://api.cogrant.eu/v1/searches/{job_id} \
  -H 'Authorization: Bearer cog_live_...'

4 · Fetch the matches

Once the job is done, pull the full match set — parsed match analysis plus complete grant-detail JSON for every match.

curl -sS https://api.cogrant.eu/v1/searches/{job_id}/matches \
  -H 'Authorization: Bearer cog_live_...'

Each row carries two nested objects:

• match — analyst-style decision block (eligibility verdict, objective / activity / budget fit, clarification questions, consortium expectations).
• grant — structured grant metadata (core_metadata, timelines, financials, eligibility_and_consortia, scope_and_activities, scope_batches, administrative).

Every individual field is documented in the Swagger reference — expand MatchDetails and GrantDetails in the schemas panel for the full list with per-field meaning.

Errors & rate limits

Every error response uses a single envelope. error.code is machine-readable; error.request_id matches the X-Request-Id header and appears in Cogrant's logs — quote it in support requests.

{
  "error": {
    "code": "JOB_NOT_READY",
    "message": "Job not yet complete.",
    "request_id": "req_7c0a1f9e4b2d88ab",
    "details": { "status": "running", "hint": "..." }
  }
}

Known codes: UNAUTHORIZED, JOB_NOT_FOUND, JOB_NOT_READY, JOB_FAILED, INVALID_REQUEST, RATE_LIMITED.

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window so you can pace requests. On a 429 the Retry-After header tells you how long until the tripped window frees up.

There are two bucket families: a general cap on all authenticated calls (minute / day / week) and a stricter cap on POST /v1/searches alone (searches_day / searches_week). Polling status and fetching matches hit only the general buckets — feel free to poll freely.

Idempotency

Pass an Idempotency-Key header on POST /v1/searches to make calls safely retryable. A repeat with the same key returns the original job and sets Idempotency-Replayed: true.

Interactive reference

The full OpenAPI schema lives at /openapi.json. A ready-to-try Swagger UI is mounted at /docs — hit the Authorize button and test every endpoint from your browser.