HTTP API¶
Every photo-checks route, for any language. The SDK calls exactly these.
Base URL and key¶
Send your API key in an X-Api-Key header. (An api_key form or JSON field
also works, the way the prediction API takes it.)
The key needs the Photo checks permission for every route here except the webhook's three, which need Results webhook. Permissions are chosen when a key is made, at Company → API keys.
Routes¶
| Method | Path | What it does |
|---|---|---|
POST |
/checks/photos |
Send one photo. Opens the job on first use. |
GET |
/checks/jobs/by-external/{jobId} |
The job by your own id: verdict, checks, what is still missing. |
POST |
/checks/jobs/by-external/{jobId}/complete |
No more photos: anything still missing now fails. |
DELETE |
/checks/jobs/by-external/{jobId}/photos/{photoId} |
Take a photo out and judge the job again. |
PATCH |
/checks/jobs/by-external/{jobId} |
Change an open job's own data (fields), parameter values (params) or site, and judge it again. |
GET |
/checks/jobs?site={siteKey}&outcomes=fail,needs_review |
Every job at a site that did not pass. |
GET |
/checks/jobs/by-external/{jobId}/photos/{photoId}/annotated |
The photo with its boxes drawn on (JPEG). |
GET |
/checks/classes |
What your model can find: the names detect takes. |
GET |
/checks/templates |
Your account's live check templates, with their photo slots and checks. |
GET |
/checks/templates/{templateKey} |
One of them, plus the live version's whole definition. |
GET |
/checks/templates/{templateKey}/parameters |
A template's settings (type, default, who may set each) and the values set, for your account and per site. |
PUT |
/checks/templates/{templateKey}/parameters?scope=site:{siteKey} |
Set the values for one site (or scope=account): {"values": {...}, "reason": "..."}. A new version, kept with who set it and why. |
GET |
/checks/templates/{templateKey}/parameters/history?scope=... |
One scope's values now and every version before. |
PUT |
/checks/webhook |
Set the address results are sent to. The answer holds the signing secret, shown once. |
GET |
/checks/webhook |
The address (never the secret). |
DELETE |
/checks/webhook |
Stop sending results. |
GET |
/checks/jobs/by-external/{jobId}/deliveries |
What was sent for a job, and how it went. |
Ids in paths are your own; escape them (encodeURIComponent), since a photo id
such as an S3 key can contain /.
Send a photo¶
curl -X POST https://sightapi.raku.so/checks/photos \
-H "X-Api-Key: $SIGHT_API_KEY" -H "Content-Type: application/json" \
-d '{
"external_job_id": "task-42",
"template": "site-completion",
"slot": "front_view",
"image_url": "https://your-bucket.s3.amazonaws.com/photo-7.jpg?X-Amz-Signature=...",
"external_photo_id": "photo-7",
"site": {"key": "site-9"},
"readings": {"serial": "AB12345678"},
"detect": ["front_door", "meter"],
"mode": "fast"
}'
mode is async (202 at once), fast or sync; see
Sending photos.
A template written in checks v2 can also compare the photos with your own data
about the job: send it as "fields": {"expected_serial": "AB12345678"} with
any photo, or change it later with PATCH. It is optional: a check that needs
something you did not send needs review or does not apply, and is never failed
for it.
Your templates and their photo slots¶
template and slot above must be written exactly as your template names
them. List them instead of typing them:
{
"templates": [
{
"key": "site-completion",
"name": "Site complete",
"version": 2,
"calibrated": false,
"provisional": true,
"slots": [
{"key": "front_view", "label": "Front view", "required": true},
{"key": "Meter_Screen", "label": "Meter screen", "required": false}
],
"uses_classes": ["front_door", "meter"],
"checks": [
{"key": "door_present", "name": "Front door in the photo", "photos": {"slot": ["front_view"]},
"requires": [], "ask": "Take a photo of the front door.",
"sentence": "At least one Front view photo shows at least 1 front door.", "details": []},
{"key": "meter_reading", "name": "Meter reading in range",
"photos": {"slot": ["Meter_Screen", "front_view"]}, "requires": [],
"ask": "Take a photo of the meter's screen.",
"sentence": "At least one Meter screen or Front view photo shows reading from 10 to 20.",
"details": ["Any other answer goes to a person."]}
]
}
]
}
| Field | Meaning |
|---|---|
version |
The live version: the one a new job uses. Drafts and retired versions are never listed. |
slots[].key |
What to send as slot. |
slots[].label |
For people. Made from the key when the template gives none (front_view becomes "Front view"). |
slots[].required |
True when a job cannot pass without a photo in this slot (a check looks at it alone). |
uses_classes |
What the checks need your model to find; compare with /checks/classes. |
checks[].photos.slot |
The slots a check looks at; empty means any slot. |
checks[].sentence |
What must be true for the check to pass, in one short line of plain English made from its rule, with the same slot labels. Show the check's name as the headline, then this line, then details. The same rule always reads the same; it says what is checked, not how sure the model must be. |
checks[].details |
A line each for everything else that decides the outcome, in a fixed order: what fails it or goes to a person, a second opinion, what happens when something is not seen or a photo is missing, the check it depends on, when it applies, its severity, and which photos it looks at when sentence leaves them out. Often empty. |
GET /checks/templates/{templateKey} answers the same for one template, plus
definition, the live version's whole template. A key your account does not
have answers 404, whether or not another account uses it.
The job, as every route answers it¶
{
"job_id": "1f0c…",
"external_id": "task-42",
"state": "open",
"verdict": "needs_review",
"template": {"key": "site-completion", "version": 2},
"models": {"Site Model": "v3"},
"photos": 3,
"photos_judged": 3,
"checking": false,
"checks": [
{
"key": "meter_reading",
"name": "Meter reading in range",
"outcome": "needs_review",
"confidence": 0.62,
"reason": "partly unclear: value unclear",
"evidence": [{"photo_id": "9a2e…", "external_photo_id": "photo-7", "box": [120, 80, 410, 300],
"reading": {"value": "unclear"}, "source": "gemini"}],
"retake_helps": true,
"ask": "Retake the meter photo so the screen is sharp."
}
],
"still_missing": [
{"check": "front_view", "name": "Front of the site", "outcome": "missing",
"why": "no photo yet in front_view", "ask": "Take a photo of the front of the site."}
],
"found": [
{"photo_id": "9a2e…", "external_photo_id": "photo-7", "slot": "front_view", "detect": ["front_door", "meter"],
"detections": [{"class": "meter", "score": 0.91, "box": [120, 80, 410, 300], "confident": true}]}
],
"photo_models": [
{"photo_id": "9a2e…", "external_photo_id": "photo-7", "slot": "front_view",
"model": {"name": "Site Model", "version": 3, "model_id": 172}}
]
}
| Field | Meaning |
|---|---|
verdict |
pass, fail, needs_review or incomplete. |
checks[].outcome |
pass, fail, needs_review, not_assessable, missing, pending or not_applicable (see Outcomes). |
checks[].retake_helps |
On a check that did not pass (unless it is waiting for a reading or does not apply): true when a new or better photo could change the answer, false when only a person can settle it, such as a reading nothing can confirm yet, or a second opinion that clearly disagrees. For false, tell the user the office will check it. |
checks[].ask |
What the user should do about it, only when retake_helps is true. |
still_missing |
What the user still has to do. |
checking |
True while photos or readings are still being checked. |
photos_judged |
How many of photos the checks cover; equal once everything is checked. |
found |
For photos sent with detect: what was found of just those. |
models |
The model versions that produced this answer, by model name. Recorded when the photos were checked: an answer given before a version change keeps the version that gave it. |
photo_models |
For each photo the answer covers, the version that looked at it; model is null for a photo that was only read. |
accepted |
True on a 202: the photo was taken, and is checked moments later. |
checking_stopped |
Set when checking stopped, saying what to do. When your plan does not allow a photo of the job to be read, the job stops here with your plan's own sentence (for a photo sent with mode=async, the webhook is sent it too); it clears once the job can be judged. |
Boxes are [left, top, right, bottom] in pixels of the photo as it is shown
upright.
Errors¶
| Code | Meaning |
|---|---|
400 |
Something in the request is wrong; detail says what. |
401 |
No API key, an unknown one, or one that was revoked or has expired; detail says which and what to do. |
402 |
Your plan does not include this: this month's photos (predicted and checked count together) are used up, reading text in photos is not part of it, or a stream request (/photos/stream) is not part of it or has more photos than it takes. detail is the plan's own sentence and says what to do. A reading your device sends with the photo (readings) that fits the template is used instead of reading the photo; a job is refused for reading only while one of its photos still needs reading by us, and then its checking_stopped says so. |
403 |
This key may not do that: it lacks the permission (Photo checks, or Results webhook for the webhook). |
404 |
No such job or photo for your account. |
410 |
The photo's stored copy is gone, so it cannot be drawn. |
413 |
The photo is over 25 MB. |
503 |
Checking is briefly unavailable; try again in a few seconds. The SDK retries for you. |
Every error answers {"detail": "<what happened>"}.