Navigate API

Submit browser tasks and operate them asynchronously with a single reference. Use that reference to poll state, exchange messages, stream logs, and download artifacts.

Quickstart

End-to-end shell flow: login, create reference, poll, message, list files, cancel.

quickstart.shbash

BASE="https://navigate.sh" # 1) login and capture tokenTOKEN=$(curl -sS "$BASE/api/auth/login" \  -H 'Content-Type: application/json' \  -d '{"email":"[email protected]","password":"YourStrongPassword123!"}' \  | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])') # 2) create referenceREFERENCE=$(curl -sS "$BASE/api/references" \  -H "X-API-Key: $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"prompt":"Open example.com and report the title."}' \  | python3 -c 'import json,sys; print(json.load(sys.stdin)["reference"])') echo "reference=$REFERENCE" # 3) pollcurl -sS "$BASE/api/references/$REFERENCE" -H "X-API-Key: $TOKEN" # 4) send messagecurl -sS -X POST "$BASE/api/references/$REFERENCE/messages" \  -H "X-API-Key: $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"content":"continue"}' # 5) list filescurl -sS "$BASE/api/references/$REFERENCE/files" -H "X-API-Key: $TOKEN" # 6) optional cancelcurl -sS -X DELETE "$BASE/api/references/$REFERENCE" -H "X-API-Key: $TOKEN"

Authentication

Navigate uses API token auth for API clients. Register or log in to receive a token immediately. Send the token on every request as X-API-Key, Authorization: ApiKey, or Authorization: Bearer. You can generate and revoke long-lived keys in Settings → API Keys.

Auth Headershttp

Authorization: Bearer <token>Authorization: ApiKey <token>X-API-Key: <token>

bash

curl -sS https://navigate.sh/api/auth/register \  -H 'Content-Type: application/json' \  -d '{"email":"[email protected]","password":"YourStrongPassword123!"}'

bash

curl -sS https://navigate.sh/api/auth/login \  -H 'Content-Type: application/json' \  -d '{"email":"[email protected]","password":"YourStrongPassword123!"}'

Reference Workflow

1Call POST /api/references with a prompt.
2Store the returned reference.
3Poll GET /api/references/{reference} until terminal state.
4Use message and file routes while running.
5Optional: stream live output via /api/jobs/{reference}/stream.

Endpoints

Method	Path	Description
POST	/api/auth/register	Create an account. Returns a token and sets the Navigate cookie.
POST	/api/auth/login	Login. Returns token and sets navigate cookie.
GET	/api/account/api-keys	List active API keys for the authenticated user.
POST	/api/account/api-keys	Create a new API key (token is returned once).
DELETE	/api/account/api-keys/{id}	Revoke an API key by id.
GET	/api/scheduled-jobs	List your scheduled prompt runs.
POST	/api/scheduled-jobs	Create a scheduled prompt run with fixed times or randomized UTC windows.
PATCH	/api/scheduled-jobs/{id}	Update prompt, cadence, randomized window settings, or enabled state.
DELETE	/api/scheduled-jobs/{id}	Delete a scheduled prompt run.
POST	/api/references	Create a new reference (async run).
GET	/api/references	List recent references for the authenticated user.
GET	/api/references/{reference}	Poll status, output, and operation URLs.
DELETE	/api/references/{reference}	Cancel/finish an active reference.
POST	/api/references/{reference}/messages	Send a user message into the reference thread.
GET	/api/references/{reference}/messages	List thread messages, supports ?after and ?role.
GET	/api/references/{reference}/files	List artifacts. Add ?include_data=true to include base64 payloads.
GET	/api/references/{reference}/files/{fileId}	Download a file artifact (binary response).
GET	/api/jobs/{reference}/stream	Server-sent events stream for live output.
GET	/api/jobs/{reference}/stream-info	Browser stream state plus proxied viewer/WebSocket URLs.
GET	/api/jobs/{reference}/screenshot	Single proxied screenshot (jpeg) when available.
GET	/api/jobs/{reference}/recording	Get browser stream recording playback/download URLs when available.

Examples

Create a reference

Requestbash

curl -sS https://navigate.sh/api/references \  -H "X-API-Key: $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"prompt":"Open docs.python.org and summarize dataclasses", "testMode": false}'

Responsejson

{  "reference": "544c9ac1-57c6-4a3c-8fef-0721944795d9",  "status": "running",  "thread_id": "8e646547-6d08-47af-b46f-505b0f344386",  "operations": {    "state": "/api/references/544c9ac1-...",    "messages": "/api/references/544c9ac1-.../messages",    "files": "/api/references/544c9ac1-.../files",    "stream": "/api/jobs/544c9ac1-.../stream",    "recording": "/api/jobs/544c9ac1-.../recording"  }}

Poll state

bash

curl -sS https://navigate.sh/api/references/$REFERENCE \  -H "X-API-Key: $TOKEN"

Send message

bash

curl -sS -X POST https://navigate.sh/api/references/$REFERENCE/messages \  -H "X-API-Key: $TOKEN" \  -H 'Content-Type: application/json' \  -d '{"content":"Please export results as JSON and CSV."}'

List files

bash

curl -sS https://navigate.sh/api/references/$REFERENCE/files \  -H "X-API-Key: $TOKEN"

Download file

bash

curl -L -sS "https://navigate.sh/api/references/$REFERENCE/files/$FILE_ID" \  -H "X-API-Key: $TOKEN" \  -o artifact.bin

Stream live output (SSE)

bash

curl -N -sS "https://navigate.sh/api/jobs/$REFERENCE/stream" \  -H "X-API-Key: $TOKEN"

Errors and Status Codes

401Not authenticated or invalid API token.

404Reference, thread, or file not found.

409Invalid state transition, for example canceling a finished run.

502/503Upstream browser stream unavailable.

navigate.sh