Skip to content

HTTP API

Every photo-checks route, for any language. The SDK calls exactly these.

Base URL and key

https://sightapi.raku.so

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:

curl -s https://sightapi.raku.so/checks/templates -H "X-Api-Key: $SIGHT_API_KEY"
{
  "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>"}.