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.)

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.
`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.
`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.

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},
  "photos": 3,
  "photos_judged": 3,
  "checking": false,
  "checks": [
    {
      "key": "meter_reading",
      "name": "Meter reading in range",
      "outcome": "needs_review",
      "confidence": 0.62,
      "reason": "read 1477, expected 1490",
      "evidence": [{"photo_id": "9a2e…", "external_photo_id": "photo-7", "box": [120, 80, 410, 300],
                    "reading": {"value": "1477"}, "source": "gemini"}],
      "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}]}
  ]
}

Field	Meaning
`verdict`	`pass`, `fail`, `needs_review` or `incomplete`.
`checks[].outcome`	`pass`, `fail`, `needs_review`, `not_assessable`, `missing` or `pending` (see Outcomes).
`checks[].ask`	What the user should do about it, when it did not pass.
`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.
`accepted`	True on a 202: the photo was taken, and is checked moments later.

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, or not a valid one.
`403`	This key may not do that (for example, manage 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>"}.