Blue API documentation

Get started with the Blue API.

Authenticate with a key, select or create an operation, add a map and an area of operations, then run terrain preparation and use the results for analysis. Every example is available in Bash and Python; Bash is selected by default.

View the resource orderBrowse API reference
Resource order

Prepare the terrain, then use it for analysis.

Use existing resources when they already exist. Otherwise follow this order:

1

Operation

The top-level workspace. Access to maps and other resources is checked through the operation.

2

Map

A map belongs to an operation. Terrain layers and boundaries belong to a map.

3

Area of operations

A GeoJSON boundary layer on the map. Terrain preparation and later workflows use this polygon.

4

Prepare terrain data

The terrain-analysis job prepares elevation, slope, land cover, roads, soil, and related map products. Poll it until the data is ready.

5

Analyze and act

Use the terrain agent, pathfinding, landing-zone surveys, radar and RF analysis, or other geoprocessing tools with the prepared map.

01 · API key

Configure the API URL and key.

A Blue administrator must create an API key for your account. Python examples use the requests package and the same BLUE_API_KEY environment variable.

Configuration
# Production API
export BLUE_API_URL="https://service-blue.exialabs.com"

# Development API
# export BLUE_API_URL="https://service-blue.dev.exialabs.com"

export BLUE_API_KEY="YOUR_API_KEY"
Use the API hostnameProduction uses service-blue.exialabs.com. Development uses service-blue.dev.exialabs.com. The corresponding blue... hostnames serve the web application, not the API.
02 · Operation

Select an operation or create one.

List the operations available to the account associated with the key.

List operations
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Accept: application/json" \
  "${BLUE_API_URL}/api/operations/?force_all=true"

Copy the id of the operation you want to use. If you need a new operation, create one and use the id from its response.

Create an operation
curl --silent --show-error --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "API Terrain Test",
    "unit": "1-23 IN",
    "branch": "Army",
    "echelon": "Battalion"
  }' \
  "${BLUE_API_URL}/api/operations/"
03 · Map

Select a map in the operation or create one.

Replace YOUR_OPERATION_ID with the operation ID from the previous step.

List maps
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Accept: application/json" \
  "${BLUE_API_URL}/api/maps/?operation_id=YOUR_OPERATION_ID"

Operations created through the API do not include a map. If the list is empty, create one and copy the id from its response.

Create a map
curl --silent --show-error --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "operation_id": "YOUR_OPERATION_ID",
    "name": "Terrain Workspace"
  }' \
  "${BLUE_API_URL}/api/maps/"
04 · Area of operations

Get or create the terrain boundary.

Replace YOUR_MAP_ID and check whether the map already has a boundary.

List boundary layers
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Accept: application/json" \
  "${BLUE_API_URL}/api/map-layers/?map_id=YOUR_MAP_ID&layer_type=boundary"

If a boundary exists, use its json_data as the boundary_shape in the terrain request. Otherwise create a boundary layer. GeoJSON positions use longitude first, latitude second, and the final coordinate closes the polygon.

Create boundary layer
curl --silent --show-error --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "map_id": "YOUR_MAP_ID",
    "name": "Area of Operations",
    "layer_type": "boundary",
    "json_data": {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-93.1213, 31.1275],
          [-93.1207, 31.0890],
          [-93.0442, 31.0880],
          [-93.0439, 31.1283],
          [-93.1213, 31.1275]
        ]]
      }
    }
  }' \
  "${BLUE_API_URL}/api/map-layers/"
05 · Terrain preparation

Prepare terrain products for the map.

The API calls this terrain analysis. It generates the terrain data used by the agent and other geoprocessing tools. Send the same GeoJSON used for the boundary layer and copy the job_id from the response.

Start terrain analysis
curl --silent --show-error --fail-with-body \
  -X POST \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "map_id": "YOUR_MAP_ID",
    "boundary_shape": {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-93.1213, 31.1275],
          [-93.1207, 31.0890],
          [-93.0442, 31.0880],
          [-93.0439, 31.1283],
          [-93.1213, 31.1275]
        ]]
      }
    }
  }' \
  "${BLUE_API_URL}/api/terrain-analysis/"
06 · Job status

Wait for terrain preparation to finish.

Replace YOUR_JOB_ID with the returned job ID. Repeat while the status is pending or in_progress. A completed job reports success.

Get terrain job
curl --silent --show-error --fail-with-body \
  -H "Authorization: Bearer ${BLUE_API_KEY}" \
  -H "Accept: application/json" \
  "${BLUE_API_URL}/api/terrain-analysis/jobs/YOUR_JOB_ID"
Readiness fieldsanalysis_ready means the source data is ready for analysis. display_readymeans the generated display layers are also complete.
07 · Use the terrain

Use the prepared terrain for analysis.

Once analysis_ready is true, downstream workflows can use the terrain products generated for the map. Continue using the same map ID and area of operations.

Streaming · SSE

Use the terrain agent

Ask questions about the analyzed area, inspect terrain and operational context, and let the agent call terrain tools. Responses stream as structured server-sent events.

Terrain Analysis API Mobility

Calculate routes

Run pathfinding between two points using roads, land cover, slope, ruggedness, and mobility settings. Generated routes can be saved as map layers.

Pathfinding API Aviation

Survey landing zones

Find candidate landing zones for an aircraft platform using elevation, terrain constraints, mobility, and the selected boundary.

Landing Zones API Sensors

Model radar and RF coverage

Generate radar terrain masks or run RF propagation analysis for transmitters inside the area of operations.

Terrain Analysis API Map products

Display and query terrain data

Use generated elevation, slope, land-cover, road, soil, and analysis layers in maps and other applications.

Terrain Tiles API
Wait for the required readiness stateUse analysis_ready for analysis-based requests. Clients that render generated display layers should also wait for display_ready.
08 · Common failures

Check the status code and resource IDs.

401

Key rejected

The bearer token is missing, invalid, expired, or revoked.

403

Access denied

The account does not have access to the selected operation or resource.

404

Resource missing

Check the operation, map, layer, or job ID and its parent resource.

422

Invalid request

Check required fields, snake_case names, UUIDs, and GeoJSON coordinates.

  • A map must reference an operation available to the key.
  • The boundary layer and terrain request must use the same map ID.
  • The GeoJSON polygon ring must be closed and use [longitude, latitude].
  • Use the returned job ID when checking terrain-analysis progress.
Other resources and endpoints

Continue to the full Blue API reference.

Open API reference