The API
Everything the web interface does, your own software can do. It is a JSON API over
HTTPS at /api/v1, on your operator's address.
The two reasons people reach for it: pulling results into something else — a farm management system, a report, a spreadsheet that updates itself — and labelling in the field on a tablet, where you can see whether the thing in the imagery is the thing you meant.
Finding your address
If your software does not know which operator it belongs to yet, ask:
POST https://www.outbackdrone.com/api/v1/tenants/discover
{"username": "you@example.com"}
It returns the operators that address can sign in to. Everything after this goes to that operator's host.
Getting a token
POST /api/v1/tokens
{"username": "you@example.com", "password": "…", "name": "Field tablet"}
The only route that works without a token. It returns one — shown once, and not recoverable — which you send on every other request:
Authorization: Bearer <token>
Name it after the thing that holds it, so that revoking a lost tablet does not
mean guessing which of four tokens it had. Pass expires_in_days to make it
expire; a token on a device that goes into the field should.
GET /api/v1/tokens lists them, DELETE /api/v1/tokens/{id} revokes one
immediately, and GET /api/v1/me says who a token belongs to.
A token carries the permissions of the person who made it. A token issued by a viewer can read and export and nothing else. See People and access.
Surveys
GET /api/v1/projects
GET /api/v1/surveys
GET /api/v1/surveys/{id}
GET /api/v1/surveys/{id}/frames
GET /api/v1/jobs
jobs is what you poll while something is processing.
Analyses
GET /api/v1/analyses/catalogue what can be asked
POST /api/v1/analyses ask
GET /api/v1/surveys/{id}/analyses
GET /api/v1/analyses/{id} poll, then read the features
GET /api/v1/analyses/{id}/route the order to visit findings in
GET /api/v1/analyses/{id}/export/{format}
An analysis outlives its request, so this is ask, poll, read rather than one call that waits. Poll sensibly — every few seconds while it is running, not continuously.
Exports
GET /api/v1/surveys/{id}/exports
POST /api/v1/surveys/{id}/exports ask for one
GET /api/v1/exports/{id} poll
GET /api/v1/exports/{id}/download
GET /api/v1/surveys/{id}/report
Three steps for the same reason: building a large export takes real time.
Models
GET /api/v1/models
POST /api/v1/models
GET /api/v1/models/{id}
GET /api/v1/models/{id}/labels
POST /api/v1/models/{id}/labels
DELETE /api/v1/models/{id}/labels/{labelId}
POST /api/v1/models/{id}/train
POST /api/v1/models/{id}/activate/{versionId}
This is the field-labelling surface. Fetch the model, post outlines as you walk the ground, and train when you have enough. See Training a model.
Drones
GET /api/v1/drones
POST /api/v1/drones
PATCH /api/v1/drones/{id}
DELETE /api/v1/drones/{id}
The planner reads this, and it is the only way to fly an aircraft the platform does not ship a specification for.
Errors
Ordinary HTTP status codes, with a body that names the problem:
{"error": "invalid_credentials",
"message": "That username and password were not accepted."}
401 means the token is wrong, missing or revoked. 403 means the token is fine
and its owner may not do that. 422 means the request made sense and was refused
— which is where plan limits appear, and the message says which limit and what to
do about it.
Rules of the road
Everything is scoped to your operator. A token cannot see another operator's data. There is no parameter for it and no accident that produces it.
All coordinates are EPSG:4326 — plain latitude and longitude — in and out.
All timestamps are instants with a timezone, in ISO 8601. Convert for display at the edge; do not store the formatted string.
Poll, do not hammer. Processing is shared. A client that polls a running job ten times a second is taking capacity from the job it is waiting for.
Keep the token out of your source. An environment variable or the device's keychain. A token committed to a repository is a live credential for your entire operator, and revoking it is the only fix.