Tech.Earth for Developers

Getting access

Access is by API key, issued to named partners - there is no self-service signup in this version. Contact your Tech.Earth account manager to request a key; they will confirm which scopes and rate limit tier are appropriate for your use case and share the key with you through a secure channel.

Every request - REST or MCP - must include Authorization: Bearer <your key>. Keys are scoped (below) and rate-limited per key, per tier.

Scopes & rate limits

Every key is issued with one or more scopes. Ask your account manager for the scopes your integration needs - a key with only challenges:read cannot call cluster or brief endpoints, for example.

Scopes govern what you can call. Which records you see is a separate, non-negotiable boundary: endpoints that return your own submissions, ownership claims or research runs are always filtered to your tenant, whatever scopes your key holds. Another tenant's record returns not-found, never a permission error.

Rate limit tiers: standard (60 requests/min - the default), elevated (300/min), and internal_partner (1000/min). Limits are per key, shared across REST and MCP calls made with the same key. A request over the limit returns 429.

REST API - /v1

Base URL: https://tech.earth/api/v1. Everything returns JSON. This is a versioned, stable contract - once you integrate against it, the response shape is frozen (additive changes only).

Most endpoints are read-only GETs. Three accept a POST - research runs, submissions and ownership claims - and each of those creates a reviewable draft or request, never a published record or an approved claim. Nothing you can call here publishes a Challenge or grants ownership; a human reviewer does that, always.

Send an Idempotency-Key header with any POST. It is optional but strongly recommended: retrying with the same key returns the original result instead of creating a second record. Reusing a key with a different body is rejected with 409, as is retrying while the first request is still in flight.

lens on the brief endpoint must be one of challenge, ecosystem, venture_brief. The brief endpoint only briefs Challenges (kind: "challenge") - Cluster ids return 404 there.

Paging and incremental sync. Use updatedSince to pull only what has changed rather than re-reading the whole register; on a Challenge it compares against updatedAt, on a Cluster against the date it was last reviewed. Results are ordered by impact score with a stable id tiebreak, so offset paging will not duplicate or skip rows. The merged list (no kind) caps offset + limit at 1000, because it has to read that far into both sources before it can merge them - to page deeper, ask for one kind at a time, which has no such limit.

Every /v1 response carries an x-correlation-id header. Quote it when reporting a problem - it is the same id our request log records for your call.

Example request

$ curl https://tech.earth/api/v1/regions \
    -H "Authorization: Bearer <your key>"

{
  "regions": [
    { "code": "GB", "name": "United Kingdom", "level": "country", "countryCode": "GB", "countryName": "United Kingdom" },
    { "code": "GB-LDN", "name": "London", "level": "region", "countryCode": "GB", "countryName": "United Kingdom" },
    { "code": "GB-SCT", "name": "Scotland", "level": "region", "countryCode": "GB", "countryName": "United Kingdom" }
  ]
}

Errors

Every error response is a structured object, not a bare string:

{
  "error": {
    "category": "validation",
    "code": "validation_failed",
    "message": "limit must be an integer between 1 and 200"
  }
}

Branch on category - it is a closed set: authentication, scope, policy, validation, conflict, rate, review_state, not_found, connector, internal. code is a stable machine-readable reason within a category; message is human-readable and may be reworded, so don't match on it.

Authentication failures are deliberately undifferentiated. An invalid key, a revoked key, an expired key, a suspended key and a key whose tenant is not approved all return the same 401 with the same message - the response never tells you which, so don't try to distinguish them. Retrying will not clear any of them.

Challenges vs. clusters

/v1/challenges and /v1/challenges/{id} return a mix of two kinds, told apart by kind: a standalone "challenge" (a single declared Challenge - status, origin, and a full impact sub-score breakdown) or a "cluster" (several related Challenges grouped together - a shared pattern summary and an organisation-type breakdown instead of per-Challenge fields). Every entry - either kind - carries regions[], a list of { code, name } pairs, since a Challenge can span multiple regions. Don't hardcode region codes; call GET /v1/regions to discover them.

{
  "challenges": [
    {
      "kind": "challenge",
      "id": "3f9a1c2e-...",
      "title": "Elevated PM2.5 across East London",
      "challengeType": "air_quality",
      "impactScore": 72,
      "impactConfidence": "High",
      "regions": [{ "code": "GB-LDN", "name": "London" }],
      "evidenceCount": 14,
      "status": "active",
      "origin": "org_report",
      "createdAt": "2026-01-15T09:12:00.000Z",
      "updatedAt": "2026-03-10T16:04:00.000Z"
    },
    {
      "kind": "cluster",
      "id": "9b2e7a10-...",
      "title": "Recurring surface-water flooding, North West",
      "challengeType": "floods",
      "impactScore": 58,
      "regions": [{ "code": "GB-NW", "name": "North West" }],
      "organisationCount": 5,
      "isStrategic": true
    }
  ],
  "pagination": { "total": 214, "limit": 50, "offset": 0, "hasMore": true }
}

The Challenge record

GET /v1/challenges/{id} returns everything a list row carries, plus the blocks below. All of it is drawn from the exact version a reviewer approved for publication - never a draft, and never a newer revision still under review.

Not returned, by design: internal working notes, named individuals, and any AI-suggested relationship a reviewer has not confirmed.

MCP server (for AI agents)

Claude, Cursor, ChatGPT, or your own agent can call this same data as MCP tools over Streamable HTTP, using the same API key and scopes as the REST API - one key works across both surfaces, with one shared rate-limit budget.

{
  "mcpServers": {
    "tech-earth": {
      "url": "https://tech.earth/api/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}

Tools are filtered by your key's scopes: a tool you lack the scope for is not listed and cannot be called. The tools read the same data as the REST endpoints, through the same gates - an agent cannot reach anything a REST caller with the same key could not.

Read tools

Write tools

Each of these creates something a human then reviews. None of them publishes a Challenge, approves a claim, or changes a public record - there is no tool on this server that can.

A failed tool call returns the error as text with an error flag, rather than the JSON envelope the REST API uses. Scope denials and rate limits surface the same way - check the message, not a status code.