TerraByte API

Search the Earth. In one request.

Send a natural-language query to the same search system behind the TerraByte dashboard. Receive ranked imagery matches with coordinates, source year, and a relevance score.

Natural-language search across the imagery archive
Ranked results with latitude, longitude, year, and score
Self-serve API keys from the portal dashboard

Open TerraByte Search Request API access

Live endpoint REST / JSON

Request ready POST /v1/search

# Search the imagery archive
curl https://portal.terrabyte.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TERRABYTE_API_KEY" \
  -d '{
    "text": "oil storage tanks",
    "top_k": 50
  }'

{
  "points": [
    {
      "lat": 32.7831,
      "lon": -96.8067,
      "score": 0.74,
      "year": 2022
    }
  ]
}

Status200 OK

Formatapplication/json

ResultRanked points

Base URLhttps://portal.terrabyte.ai

EndpointPOST /v1/search

AuthenticationAPI key (Bearer)

ResponseJSON · ranked coordinates

POST

/v1/search

Search the imagery archive with a plain-English description and receive the highest-ranking geographic matches.

Request bodyapplication/json

textrequired
Natural-language description of the place or visual pattern to find.
top_koptional
Maximum number of ranked matches to return.

ResponseRanked point objects

ididentifier
The matching imagery record.
lat / loncoordinates
The geographic center of the match.
scorerelevance
The match score used to order results.
yearvintage
The source imagery year returned with the match.

Reference

What comes back, and what can go wrong?

Every response is JSON. A successful search returns points, each with lat, lon, a relevance score (a ranking signal, not a calibrated probability), and the imagery’s acquisition year. Request fields: text (required, up to 500 characters), top_k (1–200, default 100), an optional bbox as [minLon, minLat, maxLon, maxLat], and parse_nl (default true) to let TerraByte resolve places named in your query. The full contract is machine-readable at /developers/openapi.json.

Status	Meaning	Body
200	Ranked matches	`{ "points": […] }`
400	The request body failed validation	`{ "error": "invalid request body" }`
401	Missing or invalid API key	`{ "error": "missing Authorization: Bearer <api key>" }`
403	The account’s email is not verified yet	`{ "error": "email_not_verified" }`
429	Quota exhausted or rate limited — `Retry-After` says when to try again	`{ "error": "quota_exceeded", "scope": "daily", "limit": 20, "used": 20, "resets_at": … }`
502	The search backend errored	`{ "error": "gateway error" }`

Free accounts can run 20 searches a day and 100 a month. Need more? See pricing or talk to the team.

MCP

https://mcp.terrabyte.ai

Before you connect

A Claude account with custom connectors available. For a managed workspace, an owner may need to add the connector first.
A TerraByte account with a verified email, connector access, and available quota. Use the TerraByte account you want to connect to Claude.
The MCP server URL: https://mcp.terrabyte.ai. Keep credentials out of the URL.

This is a remote connector: no local server or desktop extension is required. Start in Claude on the web or Claude Desktop. TerraByte usage is metered separately from your Claude usage.

Connect to Claude

Open Customize → Connectors → Add custom connector. A Team or Enterprise owner adds it through Organization settings → Connectors → Add → Custom; choose Web if asked.
Name it TerraByte and enter https://mcp.terrabyte.ai, without a trailing slash. Choose Add or continue through the dialog.
If authentication options appear, use OAuth sign-in and Use Claude’s published identity. Leave manual client credentials and request headers empty. TerraByte supports Claude’s published client identity.
Select Connect, complete the TerraByte sign-in and consent steps below, and return to Claude.
In a conversation, open + → Connectors and enable TerraByte. Try an example below and review the tool results and any permission requests.

Claude is rolling out different connector dialogs. See Claude’s remote connector instructions for current controls.

Tool Examples

Try one of these prompts in Claude. Results depend on available data and your TerraByte quota.

1. Discover Locations

Find me solar farms in Arizona.

2. Find and retrieve GIS records

Find warehouse-use records and FEMA flood-zone layers for Pembroke Pines, Florida.

3. View satellite context

Show satellite imagery of Tampa’s port area, including its capture date and resolution.

4. View Live Events

Find wildfires near Los Angeles, California.

Troubleshooting

Connection fails: Check that the URL is https://mcp.terrabyte.ai. Add it through Claude’s connector settings. If Claude itself fails to connect, send the error and URL to support; do not substitute a development host.
Sign-in fails, consent is denied, or the connection expires: Confirm the account and environment. For email_not_verified, complete email verification first. After denial, restart from Claude if you want to grant access. For invalid_token or an expired connection, reconnect and sign in again. If the sign-in loop continues, try another browser and report the error. See Claude’s authentication troubleshooting.
Quota exceeded or rate limited: For quota_exceeded, read scope, used, limit, and resets_at in the result. Check your TerraByte account’s usage or ask support about access. Wait until the stated reset; reconnecting does not reset quota. For a temporary rate limit, respect any retry delay and avoid repeated retries. Free Sentinel-2 imagery can still consume TerraByte tool quota.
A tool is missing, blocked, or unavailable: Enable TerraByte in this conversation and check its tool permissions. A workspace owner may control access. Tools also depend on the connected environment and service configuration; do not assume every advertised capability is enabled for your account. If an available tool repeatedly fails, report its name and error.
No locations or GIS records are returned: Check the resolved place and bounding box. Try a broader visual description or inspect the layer’s coverage, fields, and filters. A public ArcGIS service may not be in TerraByte’s index. Read paging and truncation indicators before treating results as complete. No match, a null field, or an incomplete response does not prove that a feature or hazard is absent.

Support

For access, product issues, or security concerns, email info@terrabyte.ai or use the site’s contact form.

Include your Claude client, the time of the error, connection URL, tool name, and a short description of the failed step. Remove passwords, API keys, tokens, and unrelated private content from error text or screenshots.

From query to evidence

How does a query become evidence?

Describe.

Send the place, object, or visual pattern you are trying to find in ordinary language.

Rank.

TerraByte searches the imagery archive and orders matches by visual relevance.

Integrate.

Use the returned coordinates, scores, and years in your own application or review flow.