DocSpry Shelf API · Preview

Shelf API reference.
Preview.

Preview

Not open to customers yet. DocSpry has no API keys, and these routes accept only a signed-in DocSpry session: they are the routes the DocSpry Shelf app calls. Endpoints and fields may change before API access opens.

Send a shelf photo, get back facings, a neatness score with evidence, gap and price-tag checks and a fix-first list. JSON in, JSON out.

Authentication and base URL

Every request carries a DocSpry bearer token. The only token these routes will accept is a signed-in DocSpry session’s, which the DocSpry Shelf app sends for you: there are no API keys, and a connected assistant’s token is refused.

Authorization: Bearer <token>
Base URL: https://api.docspry.com

A read belongs to the account that started it. Every route answers 401 without a valid token and 404 for a read that is not yours, so ids cannot be probed. Requests and responses are JSON in camelCase, except photo uploads (multipart/form-data) and the marked-up photo (JPEG). Errors are {"error": "<code>", "message": "<sentence>"}, except a refused read, which gets the price answer.

Examples use the soft drinks sample read from the DocSpry Shelf page. Ids, times and balances are placeholders.

Quick start

Check, send, wait, fetch: four calls. There is no webhook for you: poll the read until it has ended. The examples read a bearer token from DOCSPRY_TOKEN; until API keys exist, there is no supported way to get one outside the app.

curl

API=https://api.docspry.com
AUTH="Authorization: Bearer $DOCSPRY_TOKEN"

# 1. Free quality check: retake the photo at once if it fails
curl -H "$AUTH" -F photo=@shelf.jpg $API/shelf/quality-check
# {"passed":true,"codes":[],"warnings":[]}

# 2. Send the photo (200 tokens, charged only if the read completes)
curl -H "$AUTH" -F photo=@shelf.jpg -F 'params={"storeName":"Your store"}' \
     $API/shelf/reads
# 202 {"readId":"…","status":"queued", …}
READ=<readId from the answer>

# 3. Wait: poll until read.status is completed, rejected or failed
curl -H "$AUTH" $API/shelf/reads/$READ

# 4. Fetch the marked-up photo
curl -H "$AUTH" -o annotated.jpg $API/shelf/reads/$READ/annotated.jpg

Python

import json, os, time
import requests

API = "https://api.docspry.com"
HEADERS = {"Authorization": "Bearer " + os.environ["DOCSPRY_TOKEN"]}

# 1. Free quality check: retake the photo at once if it fails
with open("shelf.jpg", "rb") as photo:
    check = requests.post(f"{API}/shelf/quality-check", headers=HEADERS,
                          files={"photo": ("shelf.jpg", photo, "image/jpeg")}).json()
if not check["passed"]:
    raise SystemExit("Retake the photo: " + ", ".join(check["codes"]))

# 2. Send the photo (402 means not enough tokens, 429 today's limit)
with open("shelf.jpg", "rb") as photo:
    created = requests.post(f"{API}/shelf/reads", headers=HEADERS,
                            files={"photo": ("shelf.jpg", photo, "image/jpeg")},
                            data={"params": json.dumps({"storeName": "Your store"})})
created.raise_for_status()
read_id = created.json()["readId"]

# 3. Wait for the read to end
while True:
    detail = requests.get(f"{API}/shelf/reads/{read_id}", headers=HEADERS).json()
    if detail["read"]["status"] not in ("queued", "processing"):
        break
    time.sleep(3)

# 4. Use the result and fetch the marked-up photo
if detail["read"]["status"] == "completed":
    result = detail["result"]
    print(result["shelf"]["neatness"]["score"], [a["reason"] for a in result["actions"]])
    image = requests.get(f"{API}/shelf/reads/{read_id}/annotated.jpg", headers=HEADERS)
    with open("annotated.jpg", "wb") as out:
        out.write(image.content)
else:
    print(detail["read"]["status"], detail["read"]["qualityCodes"], detail["read"]["error"])

C# (HttpClient)

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.docspry.com") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("DOCSPRY_TOKEN"));

// 1. Send the photo with the store's name
using var form = new MultipartFormDataContent();
var photo = new ByteArrayContent(await File.ReadAllBytesAsync("shelf.jpg"));
photo.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
form.Add(photo, "photo", "shelf.jpg");
form.Add(new StringContent("""{"storeName":"Your store"}"""), "params");
using var created = await http.PostAsync("/shelf/reads", form);
created.EnsureSuccessStatusCode();
var readId = (await created.Content.ReadFromJsonAsync<JsonElement>())
    .GetProperty("readId").GetString();

// 2. Wait for the read to end
JsonElement detail;
string? status;
do
{
    await Task.Delay(TimeSpan.FromSeconds(3));
    detail = await http.GetFromJsonAsync<JsonElement>($"/shelf/reads/{readId}");
    status = detail.GetProperty("read").GetProperty("status").GetString();
} while (status is "queued" or "processing");

// 3. Use the result and fetch the marked-up photo
if (status == "completed")
{
    var neatness = detail.GetProperty("result").GetProperty("shelf").GetProperty("neatness");
    Console.WriteLine($"Neatness {neatness.GetProperty("score")}");
    await File.WriteAllBytesAsync("annotated.jpg",
        await http.GetByteArrayAsync($"/shelf/reads/{readId}/annotated.jpg"));
}

JavaScript (fetch)

// Node 18 or later. Keep the token on your server, never in a web page.
import { readFile, writeFile } from 'node:fs/promises';

const API = 'https://api.docspry.com';
const headers = { Authorization: `Bearer ${process.env.DOCSPRY_TOKEN}` };
const json = async response => {
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
};

// 1. Send the photo with the store's name
const form = new FormData();
form.append('photo', new Blob([await readFile('shelf.jpg')], { type: 'image/jpeg' }), 'shelf.jpg');
form.append('params', JSON.stringify({ storeName: 'Your store' }));
const { readId } = await json(await fetch(`${API}/shelf/reads`, { method: 'POST', headers, body: form }));

// 2. Wait for the read to end
let detail;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  detail = await json(await fetch(`${API}/shelf/reads/${readId}`, { headers }));
} while (detail.read.status === 'queued' || detail.read.status === 'processing');

// 3. Use the result and fetch the marked-up photo
if (detail.read.status === 'completed') {
  console.log(detail.result.shelf.neatness.score, detail.result.actions.map(a => a.reason));
  const image = await fetch(`${API}/shelf/reads/${readId}/annotated.jpg`, { headers });
  await writeFile('annotated.jpg', Buffer.from(await image.arrayBuffer()));
}

A real response, trimmed

From the soft drinks sample: the score, the share of facings and the actions of its result.

{
  "neatness": {
    "score": 91,
    "stars": 5,
    "subScores": {
      "fronting": 94,
      "alignment": 94,
      "gaps": 94,
      "blocking": 100,
      "condition": 100,
      "labelling": 50
    }
  },
  "shareOfShelf": [
    {
      "brand": "Coca-Cola",
      "facingsPct": 12.5
    },
    {
      "brand": "Fanta",
      "facingsPct": 25
    },
    {
      "brand": "L&P",
      "facingsPct": 31.25
    },
    {
      "brand": "Lift",
      "facingsPct": 6.25
    },
    {
      "brand": "Sprite",
      "facingsPct": 25
    }
  ],
  "actions": [
    {
      "priority": 1,
      "type": "restock",
      "facingId": null,
      "row": 4,
      "reason": "empty slot on shelf"
    },
    {
      "priority": 3,
      "type": "fix_orientation",
      "facingId": 1,
      "row": 0,
      "reason": "pack is side"
    }
  ]
}

Before a read

GET /shelf/price

What a photo costs now, what you hold, how many reads today still allows, and why a read would be refused if it would be.

Request

curl -H "Authorization: Bearer $DOCSPRY_TOKEN" https://api.docspry.com/shelf/price

Response

{
  "tokensPerPhoto": 200,
  "balance": "<your balance>",
  "readsLeftToday": 50,
  "refusal": null
}

Status codes

  • 200 The price answer. refusal is null when a read is allowed now.
  • 401 No valid token.

POST /shelf/quality-check

Checks a photo for blur, exposure, glare and size before you send it for a read. Free: nothing is stored or charged, and it is not a read. Up to 300 a day.

ParameterInDescription
photoform (file)The shelf photo: JPEG, PNG or WebP, up to 20 MB.

Request

curl -H "Authorization: Bearer $DOCSPRY_TOKEN" \
     -F photo=@shelf.jpg https://api.docspry.com/shelf/quality-check

Response (all three sample photos passed)

{
  "passed": true,
  "codes": [],
  "warnings": []
}

Status codes

  • 200 Checked. passed is false when codes lists a reason: blur, underexposed, overexposed, glare or too_small (long edge under 800 px). A tilted photo is a warning, photo_tilted, not a rejection.
  • 400 bad_request: no photo.
  • 413 too_large.
  • 415 unsupported_type.
  • 429 daily_checks_exceeded.

Reads

POST /shelf/reads

Sends one photo for a read. The read runs in the background: you get its id at once, then poll it. The wallet and today’s limits are checked first; 200 tokens are charged only when the read completes.

ParameterInDescription
photoform (file)JPEG, PNG or WebP, up to 20 MB. One shelf section per photo gives the best result.
paramsform (JSON text)Optional. The fields below.
params.storeNameJSONThe store, as you name it. Up to 200 characters.
params.visitId, params.visitPhaseJSONOptional. Groups the photos of one store visit, pre or post its work; a phase needs an id. No visit report is offered yet.
params.expectedFixturesJSONOptional. Up to 20 names of displays this shelf should have. One the read does not find at first gets a second look with the name, and the result then warns fixture_found_with_hint.

Request

curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -F photo=@shelf.jpg \
     -F 'params={"storeName":"Your store"}' \
     https://api.docspry.com/shelf/reads

Response: 202 Accepted

{
  "readId": "<readId>",
  "status": "queued",
  "readType": "shelf",
  "fileName": "shelf.jpg",
  "storeName": "Your store",
  "visitId": null,
  "visitPhase": null,
  "createdAt": "<UTC time>",
  "completedAt": null,
  "tokensCharged": 0,
  "neatnessScore": null,
  "stars": null,
  "facings": null,
  "actions": null,
  "qualityCodes": [],
  "error": null
}

Status codes

  • 202 Accepted and queued.
  • 400 bad_request.
  • 402 Not enough tokens, or today’s plan limit is used: the price answer with refusal.
  • 413 too_large.
  • 415 unsupported_type.
  • 429 Today’s limit of reads (the price answer with refusal), or read_busy: another photo from your account is being sent.
  • 503 shelf_busy: the photo could not be sent. The read is marked failed and not charged; the body carries its readId.

GET /shelf/reads

Your own reads, newest first, a page at a time.

ParameterInDescription
limitqueryReads per page: 20 by default, 100 at most.
cursorqueryThe next value of the page before.

Response

{
  "items": [
    {
      "readId": "<readId>",
      "status": "completed",
      "readType": "shelf",
      "fileName": "shelf.jpg",
      "storeName": "Your store",
      "visitId": null,
      "visitPhase": null,
      "createdAt": "<UTC time>",
      "completedAt": "<UTC time>",
      "tokensCharged": 200,
      "neatnessScore": 91,
      "stars": 5,
      "facings": 94,
      "actions": 2,
      "qualityCodes": [],
      "error": null
    }
  ],
  "next": null
}

Status codes

  • 200 A page of reads. next is null on the last page.
  • 400 bad_request: not a cursor of this list.

GET /shelf/reads/{readId}

The read, and its result once it has completed. The example is the soft drinks sample, with products cut to 5 of 37, realogram to 2 of 94 and priceTags to 3 of 24.

ParameterInDescription
readIdpathThe readId from POST /shelf/reads.

Response: the soft drinks sample

{
  "read": {
    "readId": "<readId>",
    "status": "completed",
    "readType": "shelf",
    "fileName": "shelf.jpg",
    "storeName": "Your store",
    "visitId": null,
    "visitPhase": null,
    "createdAt": "<UTC time>",
    "completedAt": "<UTC time>",
    "tokensCharged": 200,
    "neatnessScore": 91,
    "stars": 5,
    "facings": 94,
    "actions": 2,
    "qualityCodes": [],
    "error": null
  },
  "result": {
    "readType": "shelf",
    "image": {
      "width": 2212,
      "height": 1659
    },
    "quality": {
      "passed": true,
      "codes": []
    },
    "shelf": {
      "rows": 6,
      "displayType": "main_shelf",
      "neatness": {
        "score": 91,
        "stars": 5,
        "subScores": {
          "fronting": 94,
          "alignment": 94,
          "gaps": 94,
          "blocking": 100,
          "condition": 100,
          "labelling": 50
        },
        "evidence": [
          {
            "facingId": 1,
            "row": null,
            "issue": "orientation_side",
            "widthPx": null
          },
          {
            "facingId": null,
            "row": 4,
            "issue": "empty_slot",
            "widthPx": 365
          }
        ]
      },
      "shareOfShelf": [
        {
          "brand": "Coca-Cola",
          "isCompetitor": false,
          "facingsPct": 12.5,
          "linearPct": 10.51819864281308,
          "areaPct": 4.54120419147904
        },
        {
          "brand": "Fanta",
          "isCompetitor": false,
          "facingsPct": 25,
          "linearPct": 25.94077729796422,
          "areaPct": 49.809017123676355
        },
        {
          "brand": "L&P",
          "isCompetitor": false,
          "facingsPct": 31.25,
          "linearPct": 27.0203578038248,
          "areaPct": 18.654753379487946
        },
        {
          "brand": "Lift",
          "isCompetitor": false,
          "facingsPct": 6.25,
          "linearPct": 11.320172732880938,
          "areaPct": 8.846579935096958
        },
        {
          "brand": "Sprite",
          "isCompetitor": false,
          "facingsPct": 25,
          "linearPct": 13.942011104256633,
          "areaPct": 9.826654038260855
        }
      ],
      "gaps": [
        {
          "row": 4,
          "bbox": [
            90,
            1432,
            455,
            1659
          ]
        }
      ],
      "notes": [
        "L&P block has no price tag directly below it",
        "Lift lemon tag sits under L&P/lemon area; check tag-to-product match",
        "Fanta 1.5L has a 2 for 6.00 promo tag in place"
      ]
    },
    "products": [
      {
        "brand": "7UP",
        "name": "7UP",
        "facings": 0,
        "visibleUnits": 3,
        "estimatedUnits": null,
        "confidence": 0.8000000000000002
      },
      {
        "brand": null,
        "name": "blue drink bottle",
        "facings": 0,
        "visibleUnits": 1,
        "estimatedUnits": null,
        "confidence": 0.3
      },
      {
        "brand": null,
        "name": "dark brown soft drink",
        "facings": 0,
        "visibleUnits": 2,
        "estimatedUnits": null,
        "confidence": 0.4
      },
      {
        "brand": null,
        "name": "dark cola bottle",
        "facings": 0,
        "visibleUnits": 1,
        "estimatedUnits": null,
        "confidence": 0.4
      },
      {
        "brand": null,
        "name": "green drink bottle",
        "facings": 0,
        "visibleUnits": 1,
        "estimatedUnits": null,
        "confidence": 0.3
      }
    ],
    "realogram": [
      {
        "facingId": 1,
        "bbox": [
          125,
          66,
          300,
          660
        ],
        "row": 0,
        "position": 1,
        "frontRow": true,
        "brand": "Fanta",
        "name": "Fanta Orange",
        "observedName": "FANTA ORANGE 1.5L",
        "matchConfidence": 0.7,
        "brandLabel": {
          "visible": true,
          "readable": true,
          "orientation": "side",
          "confidence": 0.7
        },
        "condition": "ok",
        "inFixture": false
      },
      {
        "facingId": 2,
        "bbox": [
          214,
          60,
          475,
          690
        ],
        "row": 0,
        "position": 2,
        "frontRow": true,
        "brand": "Fanta",
        "name": "Fanta Orange",
        "observedName": "FANTA ORANGE 1.5L",
        "matchConfidence": 0.95,
        "brandLabel": {
          "visible": true,
          "readable": true,
          "orientation": "front",
          "confidence": 0.95
        },
        "condition": "ok",
        "inFixture": false
      }
    ],
    "priceTags": [
      {
        "bbox": [
          204,
          726,
          378,
          792
        ],
        "text": "FANTA ORANGE 1.5L 2 for 6.00 SUPER SAVER",
        "price": "6.00",
        "currency": null,
        "itemCode": null,
        "isPromo": true,
        "matchedFacingIds": [
          1,
          2,
          3
        ]
      },
      {
        "bbox": [
          848,
          650,
          972,
          712
        ],
        "text": "LIFT LEMON 1.5L 2 for 6.00 SUPER SAVER",
        "price": "6.00",
        "currency": null,
        "itemCode": null,
        "isPromo": true,
        "matchedFacingIds": []
      },
      {
        "bbox": [
          1716,
          0,
          1801,
          52
        ],
        "text": "1.99",
        "price": "1.99",
        "currency": null,
        "itemCode": null,
        "isPromo": false,
        "matchedFacingIds": []
      }
    ],
    "posm": [],
    "actions": [
      {
        "priority": 1,
        "type": "restock",
        "facingId": null,
        "row": 4,
        "reason": "empty slot on shelf"
      },
      {
        "priority": 3,
        "type": "fix_orientation",
        "facingId": 1,
        "row": 0,
        "reason": "pack is side"
      }
    ],
    "count": null,
    "judgmentStatus": "ok",
    "warnings": []
  },
  "hasAnnotatedImage": true
}

Status codes

  • 200 The read. While it runs, read.status is queued or processing and result is null.
  • 404 not_found.

Read fields

FieldWhat it holds
readIdThe read’s id. Use it in the other routes.
statusqueued, processing, completed, rejected (the photo failed the quality check; qualityCodes says why) or failed (the read could not finish; error is a plain sentence). Only completed is charged.
fileName, storeName, visitId, visitPhaseAs sent.
createdAt, completedAtUTC times.
tokensCharged200 for a completed read; 0 before then and for a rejected or failed one.
neatnessScore, stars, facings, actionsHeadline numbers of a completed read; null before.

Result fields

FieldWhat it holds
readTypeshelf, the one kind of read offered.
imageWidth and height of the photo as read, in pixels. Every bbox is [x1, y1, x2, y2] in these pixels.
qualitypassed, and the quality codes.
shelf.rows, shelf.displayTypeShelf rows found, and the display type (main_shelf).
shelf.neatnessscore 0 to 100, stars 1 to 5, the six subScores, and evidence: each deduction with its facingId or row, its issue and, for a gap, widthPx.
shelf.shareOfShelfPer brand, of the front-row packs: share of facings (facingsPct), of shelf width (linearPct) and of pack area (areaPct). Packs whose brand could not be read are unknown.
shelf.gaps, shelf.notesEmpty stretches with their row and box, and short notes the read made about the photo.
productsOne row per product as read: brand, name, front-row facings, visibleUnits, estimatedUnits and confidence.
realogramEvery pack: facingId (the number on the marked-up photo), box, row (0 is the top row), position, frontRow, brand and name as read, brandLabel (visible, readable, orientation), condition and inFixture.
priceTagsEach shelf-edge tag: box, text, price, currency, itemCode, isPromo, and the matchedFacingIds it sits under.
posmEach tray, shelf talker, floor unit or other display found: type, brand, header text, box, condition, stocked units, facings inside, own-brand facings, purityPct and confidence.
actionsThe fix-first list: priority (1 first), type (restock, fix_orientation, fix_condition …), facingId or row, and a short reason.
countNull: count reads are not offered.
judgmentStatus, warningsok; and plain warning codes: photo_tilted, photo_not_upright, no_products_detected, fixture_found_with_hint.

GET /shelf/reads/{readId}/annotated.jpg

The photo with numbered boxes drawn on it: green for a front-row pack, blue for a pack further back, red for a pack not facing front or not in good condition (a turned pack further back is boxed red too, but only a turned pack in the front row counts against the score and gets an action), orange for a gap. When a photo is read, the faces of real people it finds are blurred.

Request

curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -o annotated.jpg \
     https://api.docspry.com/shelf/reads/$READ/annotated.jpg

Status codes

  • 200 A JPEG.
  • 404 not_found, or no_image: only a completed read has one.
  • 503 shelf_busy: try again shortly.
Marked-up photo of a supermarket soft-drink bay: shelves of 1.5 and 2.25 litre bottles of orange, lemon and cola drinks above multipacks of cans, with price tags on the shelf edges and an empty stretch of shelf at the bottom left.
The soft drinks sample’s marked-up photo. Photo by Panamitsu, from Wikimedia Commons, under the CC BY 4.0. Marked up by DocSpry Shelf.

DELETE /shelf/reads/{readId}

Deletes the read: the photo, the marked-up photo and the result are erased first, then the read.

Status codes

  • 204 Deleted.
  • 404 not_found.
  • 409 read_busy: the read is still being read.
  • 503 shelf_busy: nothing changed; send it again.

Errors

StatusWhat it meansWhat to do
400bad_request: no photo part, or params is not valid (a visit phase without a visit id, a name too long, more than 20 fixtures), or a list cursor that is not one.Read message, fix the request.
401No valid bearer token.Sign in again: the DocSpry Shelf app sends the token for you.
402Not enough tokens for the read, or today’s plan limit is used. The body is the price answer, with refusal saying which.Top up, or send the photo tomorrow.
404not_found: no such read in your account; another account’s read, or one you deleted, answers 404 too. no_image: the read has no marked-up photo.Check the id. Only a completed read has a marked-up photo.
409read_busy: the read is still being read, so it cannot be deleted yet.Wait until it has ended, then delete it.
413too_large: the photo is larger than 20 MB.Send a smaller photo. A phone photo of one shelf section is plenty.
415unsupported_type: the photo is not a JPEG, PNG or WebP image.Send a JPEG, PNG or WebP photo.
429Today’s limit of reads is reached (50 completed or in progress, or 150 started): the body is the price answer with refusal. read_busy: another photo from your account is being sent at this moment. daily_checks_exceeded: 300 quality checks today.Send one photo at a time; wait for tomorrow (UTC) for the daily limits.
503shelf_unavailable: DocSpry Shelf is not switched on here yet. shelf_busy: the reading service can’t be reached right now. A new read that could not be sent is marked failed, is not charged, and the body carries its readId.Try again in a few minutes.

Limits and pricing

CallPrice
POST /shelf/reads200 tokens per completed read (₹2 worth on a paid monthly plan, before tax), at the price when the read started. A rejected photo or a read that fails is free.
Every other routeFree
  • Photos: JPEG, PNG or WebP, up to 20 MB, with a long edge of at least 800 px. A photo is read at up to 2,576 px on its long edge; the app scales a larger one down before it is sent.
  • 50 reads a person per UTC day (completed or in progress), and 150 started whatever became of them.
  • 300 quality checks a person per UTC day.
  • One photo from an account sent at a time.
  • Store names and visit ids up to 200 characters; up to 20 expected displays.
  • A read and its photos are deleted 15 days after you last open it, or after the period chosen under Settings → Privacy, like other documents; stored photos are deleted after 90 days at the latest.
  • Tokens come from your DocSpry wallet; plan allowances and daily limits apply. See plans.

Use DocSpry Shelf today.

The DocSpry Shelf app does all of this for you: sign in and send a photo of one shelf section. 200 tokens a read.

Open DocSpry Shelf