Tech.Earth for Developers

How it works

Ask Tech.Earth to research the places and problems you care about — once, or on a schedule you set — get told when a run finishes, review and decide the Challenge candidates it found, and see them alongside public Challenges and clusters. Every step is an API call, or an MCP tool if an AI agent is doing the work.

The top row happens on our side once you ask; the bottom row is you acting on what came back. You never need to keep a request open: start a run (or create a schedule), then listen for the webhook or read /events.

Your records are private to your tenant

Everything your work creates belongs to your tenant: no other partner sees it, and it never appears on the public site, even once a Tech.Earth reviewer has published it. You see public records plus your own. Asking for another partner's record returns not-found, never a permission error, so you can't even tell it exists.

What to expect

• Runs are queued. Starting one answers 202 straight away and it runs in the background. Each tenant has a limit on runs in progress and runs per month; over either, you get 429.
• You describe what to research, not how. The kind of run, its research budget and the sources it searches are set by Tech.Earth.
• Approve accepts the six fields as shown. The values on dimensions[] are accepted with approve — you do not confirm them in a separate step. Resolve overlaps[] where blocksApproval is true first. Remaining readiness issues (unusable evidence, an open contradiction, a blocking overlap, missing required text, or a dimension that was never computed) still answer 409 with the blockers. Approval creates a Challenge your tenant owns and publishes it to your tenant. It does not put that Challenge on the public site.
• A reject tells the next run why. Rejecting a candidate needs a rationale and a rejectionKind: do_not_repeat so that place, population, or framing is not proposed again, or improve so the next run replaces the candidate with what the rationale names. The next run of the same recurring research reads that choice. An improve note does not override missing evidence. Flagging needs_correction is only a correction on this candidate; it does not steer later runs.
• Notifications are never lost. Webhooks are signed and retried for about a day, and every event can be read again from /events.
• Research can keep going. A research schedule queues a run on the cadence you set (default daily, never more often than every six hours). Each run is the same as one you start yourself; later runs are steered away from candidates you already have.

Recurring research

Create a schedule once with POST /research-schedules (or the research_schedule.create MCP tool). Give it a name and the same research body you would send to start a run, plus how often to repeat it. We queue a run when it is due. You keep listening for run events the way you already do; you do not poll a clock.

• Cadence is yours. cadenceMinutes is at least 360 (6 hours) and at most 129600 (90 days); omitted, it is 1440 (24 hours). Set runTime (HH:MM) and timezone (IANA such as Europe/London or an offset such as UTC+1) to pin each tick to a local clock — 1440 minutes at 09:00 in UTC+1 is every day at 9am UTC+1. startAt sets the first run; omit it or pass a time in the past and, without a runTime, the first run is due immediately.
• Optional rotation. focuses[] (at most 20) is a list of partial run bodies. Each tick uses the next entry, in order, and whatever a focus names replaces the schedule's own value for that run. Naming places replaces both place lists.
• Each tick is a real run. It counts towards your in-progress and monthly run quotas. Over either, that tick is skipped (research_schedule.skipped, reason quota_exceeded), not failed. Runs of the same schedule never overlap: if the last one is still going, the tick is skipped (previous_run_in_progress) and the next attempt waits a full cadence.
• Later runs look for what is new. We brief each run with titles and places earlier runs of this schedule already found, and skip hotspots already covered. A finding that matches an unreviewed candidate you already have (pending review or needs correction) is merged into that card — challenge_candidate.updated— instead of opening a duplicate. A finding that matches a Challenge you already approved is not opened as a second card. challenge_candidate.created is a candidate new to you. Both are published with the run's completed or partial event.
• Refresh one Challenge you already approved. Name it with challengeId. That is the whole request: do not also send a research question, places, domains or targets. The question and places come from the Challenge. A manual refresh is POST /research-runs with that id: one run, started when you send it, with no clock. A recurring refresh is the same id on a schedule; cadenceMinutes and optional runTime are how often, and every tick refreshes that Challenge. A newer finding is its own candidate. updatesApprovedChallenge is true and existingChallenge points at that Challenge. The event is challenge_candidate.update_proposed, and its data includes existingChallengeId. Load just those cards with GET /challenge-candidates?updatesApprovedChallenge=true. Approving one attaches the new evidence. It does not rewrite the Challenge. If nothing newer is found, the run finishes with no new card: research_run.completed with challengeUpdateCount 0. A finding that is not about the named Challenge is not a card. A run or schedule without challengeId only looks for new Challenges, unless the schedule opts into the update clock below. A link_to_existing candidate with updatesApprovedChallenge false is not this update: it is a duplicate or overlap someone recommended linking.
• Optional updates on Challenges this research already published. Set refreshOwnedChallenges to true and give that check its own clock: updateCadenceMinutes (same limits as cadence), plus optional updateRunTime and updateTimezone. Example: update every 30 days at 9am UTC is updateCadenceMinutes 43200, updateRunTime 09:00, updateTimezone UTC. That tick is its own run. It does not re-ask the research question. It names up to eight Challenges this schedule already got approved, oldest evidence first, and asks only whether newer evidence exists. A newer finding is challenge_candidate.update_proposed. If nothing is newer, or this schedule has not published a Challenge yet, there is no new card (no published Challenge yet is research_schedule.skipped with reason no_owned_challenges, and the clock still moves on). Omitted, the flag is false: later discovery ticks still only look for new Challenges. Do not combine it with challengeId.
• A schedule looks after itself. Three consecutive failed runs pause it (research_schedule.paused). Seven consecutive runs that find no new candidate emit research_schedule.exhausted so you can broaden the question or pause it. PATCH status to paused or active yourself; resuming resets the failure count and makes the next run due now. DELETE stops further runs; runs already made and their candidates stay.
• How many you can keep active. Default is five active schedules per tenant (an admin can raise it). Creating one more answers 429. Pause or delete one first. Places are resolved when you create or change the schedule, so a place that does not resolve is refused then, not on the first tick.

Getting access

Access is by API key. Sign in to request access from My Account. An admin will review the request, set scopes and rate limits, and then you can generate your key in the browser — the plaintext is shown once and never stored. Admins can also issue a key directly and share it 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. Request the scopes your integration needs — a key with only challenges:read cannot call cluster endpoints, for example. An admin decides the final grant. My Account can request the two public read scopes; every other scope below is admin-grant only.

Scopes govern what you can call. Which records you see is a separate, non-negotiable boundary: endpoints that return your own submissions, ownership claims, research runs, candidates, webhooks and events are always filtered to your tenant, whatever scopes your key holds, and Challenges and clusters your tenant owns are visible to it alongside public ones. 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. Research runs, research schedules, submissions and ownership claims accept a POST that creates a reviewable draft or request. With challenge-candidates:decide you can also decide your own tenant's candidates: an approval accepts the six dimension values as shown and creates a Challenge your tenant owns, then publishes it to your tenant. Resolve blocking overlaps first; remaining readiness issues still refuse the approve. That does not put the Challenge on the public site, and nothing you can call here grants ownership; a Tech.Earth reviewer does that.

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.

The full contract, request and response schemas included, is an OpenAPI 3.1 document at /api/v1/openapi.json.

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.

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/challenges?limit=2 \
    -H "Authorization: Bearer <your key>"

{
  "challenges": [
    { "kind": "challenge", "id": "3f9a1c2e-...", "title": "Elevated PM2.5 across East London", "impactScore": 72 }
  ],
  "pagination": { "total": 1, "limit": 2, "offset": 0, "hasMore": false }
}

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

These are two different record shapes, 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). Each has its own resource: GET /v1/challenges lists Challenges only - every entry's kind is "challenge", a cluster member or not, and a cluster itself never appears there - while GET /v1/clusters lists clusters only. GET /v1/challenges/{id} is the exception: it takes either kind of id and returns whichever record it names, so kind is how you tell which one came back. Every Challenge entry, on either endpoint, carries regions[], a list of { code, name } pairs, since a Challenge can span multiple regions. Region codes and names are on each entry's regions[] — there is no separate region catalogue.

GET /v1/challenges

{
  "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"
    }
  ],
  "pagination": { "total": 214, "limit": 50, "offset": 0, "hasMore": true }
}

Getting from a cluster to its Challenges

The link runs both ways. A Challenge record carries clusters[], and every cluster from /v1/clusters carries challenges[] - its published member Challenges, each with id, title, challengeType, impactScore and updatedAt, ranked by impact score the same way /v1/challenges ranks them. Follow any id to /v1/challenges/{id} for the full record.

challenges[] lists only members that are published in their own right, so it can be shorter than distinctChallengeCount - and empty on a cluster that plainly has members. That is the anonymity model working as intended: a cluster can be publishable in aggregate while the Challenges inside it are still in review. Read a short or empty challenges[] as "not public yet", never as missing data, and read organisationCount, organisationTypeBreakdown and distinctChallengeCount for the true size of the cluster. Nothing in challenges[] names an organisation.

A cluster also carries domains[] and domainSource. Nothing declares a domain at cluster level, so these are the domains its published members declare, deduplicated and ordered by how many of them declare each - most first, ties alphabetical - with each member's own domains on its entry in challenges[] so you can check the union against what it came from. domainSource is "member_challenges" when at least one published member declared a domain, and "undeclared" with an empty domains[] when none did or no member is published yet. We never classify a cluster's own title or shared pattern onto the six domains - the same rule that governs a Challenge - so an empty list means nobody declared one, not that the cluster has none.

GET /v1/clusters

{
  "clusters": [
    {
      "id": "9b2e7a10-...",
      "title": "Recurring surface-water flooding, North West",
      "challengeType": "floods",
      "demandState": "expressed",
      "organisationCount": 5,
      "distinctChallengeCount": 4,
      "domains": ["climate resilience", "water"],
      "domainSource": "member_challenges",
      "challenges": [
        {
          "id": "3f9a1c2e-...",
          "title": "Surface-water flooding on the A5103 corridor",
          "challengeType": "floods",
          "impactScore": 64,
          "updatedAt": "2026-03-10T16:04:00.000Z",
          "domains": ["climate resilience"]
        }
      ]
    }
  ],
  "pagination": { "total": 37, "limit": 50, "offset": 0, "hasMore": false }
}

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, or decides your own tenant's candidates and clusters. 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.