REST API

Query physical-world context over HTTP and receive structured understanding your product can act on immediately.

Run a perception query

Discover can identify objects, infrastructure, branded entities, natural features, spatial relationships, conditions, and uploaded spatial data. By default it waits for answer generation and returns the complete public response in one HTTP 200.

POST /v1/compute

curl -X POST https://api.outerview.ai/v1/compute \
  -H "Authorization: Bearer $OUTERVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shops near parks in Toronto",
    "limit": 100,
    "answer": true,
    "coordinates": [
      { "name": "Downtown Toronto", "latitude": 43.6532, "longitude": -79.3832 }
    ]
  }'

Request fields

limit controls only the response size. Outerview may compute and save the complete result set for answer generation and continued context.

querystring · required

Physical-world question or instruction.

limitinteger · 100

GeoJSON features returned. Minimum 1; maximum 2000.

answerboolean · true

Generate and wait for a written answer. Set false to return results without an answer.

user_idstring

Optional user identifier associated with the saved query.

area_idUUID

Public area identifier used to constrain discovery.

coordinatesobject[]

Optional named coordinate references for /v1/find. Each object includes name, latitude, and longitude.

h3_idsstring | string[]

One or more H3 cells used as spatial constraints.

include_statsauto | boolean

Controls internal statistical processing. Raw diagnostics are not returned.

measurementstring

Measurement such as count, per_capita, or per_area.

modestring · default

Discovery reasoning mode.

modelstring · compute

Output model. Use compute.

search_idUUID

Public ID of an earlier query to continue.

imagesFile[]

Optional reference images in a multipart request.

filesFile[]

Optional CSV or GeoJSON files in a multipart request.

Response shape

The public response contains exactly id, query, answer, results, warnings, and usage. Coordinates use GeoJSON order: longitude first, latitude second.

200 response

{
  "id": "19011f5f-7156-4f5d-9d7e-2deef439005f",
  "query": "coffee shops near parks in Toronto",
  "answer": {
    "status": "complete",
    "content": "The strongest matches cluster around downtown parks...",
    "error": null
  },
  "results": {
    "type": "FeatureCollection",
    "numberMatched": 684,
    "numberReturned": 100,
    "features": [
      {
        "type": "Feature",
        "id": "coffee:123",
        "geometry": {
          "type": "Point",
          "coordinates": [-79.3832, 43.6532]
        },
        "properties": {
          "source_id": "123",
          "name": "Example Coffee",
          "address": "123 King St W, Toronto",
          "score": 0.92,
          "distance_meters": 180,
          "source": {
            "name": "OpenStreetMap",
            "url": "https://www.openstreetmap.org/"
          },
          "attributes": {}
        }
      }
    ]
  },
  "warnings": [],
  "usage": { "meters": 14342.2 }
}

Answer status

completestatus

content contains the generated answer and error is null.

skippedstatus

Returned when answer is false; content and error are null.

failedstatus

Retrieval succeeded but answer generation failed. Results remain usable and the request still returns HTTP 200.

Upload CSV or GeoJSON

Use multipart form data. Repeat files to attach more than one file; uploaded custom columns are isolated under properties.attributes.

Multipart request

curl -X POST https://api.outerview.ai/v1/compute \
  -H "Authorization: Bearer $OUTERVIEW_API_KEY" \
  -F "query=Find stop signs near my buildings" \
  -F "limit=250" \
  -F "answer=true" \
  -F "files=@./buildings.csv" \
  -F "files=@./service-areas.geojson"

Continue with context

Pass a prior public discovery ID in search_id to ask a follow-up question against its saved physical-world context.

Request body

{
  "query": "Now show only the closest options",
  "search_id": "19011f5f-7156-4f5d-9d7e-2deef439005f",
  "limit": 25
}