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.comA 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.jpgPython
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/priceResponse
{
"tokensPerPhoto": 200,
"balance": "<your balance>",
"readsLeftToday": 50,
"refusal": null
}Status codes
200The price answer.refusalis null when a read is allowed now.401No 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.
| Parameter | In | Description |
|---|---|---|
photo | form (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-checkResponse (all three sample photos passed)
{
"passed": true,
"codes": [],
"warnings": []
}Status codes
200Checked.passedis false whencodeslists a reason:blur,underexposed,overexposed,glareortoo_small(long edge under 800 px). A tilted photo is a warning,photo_tilted, not a rejection.400bad_request: no photo.413too_large.415unsupported_type.429daily_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.
| Parameter | In | Description |
|---|---|---|
photo | form (file) | JPEG, PNG or WebP, up to 20 MB. One shelf section per photo gives the best result. |
params | form (JSON text) | Optional. The fields below. |
params.storeName | JSON | The store, as you name it. Up to 200 characters. |
params.visitId, params.visitPhase | JSON | Optional. Groups the photos of one store visit, pre or post its work; a phase needs an id. No visit report is offered yet. |
params.expectedFixtures | JSON | Optional. 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/readsResponse: 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
202Accepted and queued.400bad_request.402Not enough tokens, or today’s plan limit is used: the price answer withrefusal.413too_large.415unsupported_type.429Today’s limit of reads (the price answer withrefusal), orread_busy: another photo from your account is being sent.503shelf_busy: the photo could not be sent. The read is marked failed and not charged; the body carries itsreadId.
GET /shelf/reads
Your own reads, newest first, a page at a time.
| Parameter | In | Description |
|---|---|---|
limit | query | Reads per page: 20 by default, 100 at most. |
cursor | query | The 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
200A page of reads.nextis null on the last page.400bad_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.
| Parameter | In | Description |
|---|---|---|
readId | path | The 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
200The read. While it runs,read.statusisqueuedorprocessingandresultis null.404not_found.
Read fields
| Field | What it holds |
|---|---|
readId | The read’s id. Use it in the other routes. |
status | queued, 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, visitPhase | As sent. |
createdAt, completedAt | UTC times. |
tokensCharged | 200 for a completed read; 0 before then and for a rejected or failed one. |
neatnessScore, stars, facings, actions | Headline numbers of a completed read; null before. |
Result fields
| Field | What it holds |
|---|---|
readType | shelf, the one kind of read offered. |
image | Width and height of the photo as read, in pixels. Every bbox is [x1, y1, x2, y2] in these pixels. |
quality | passed, and the quality codes. |
shelf.rows, shelf.displayType | Shelf rows found, and the display type (main_shelf). |
shelf.neatness | score 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.shareOfShelf | Per 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.notes | Empty stretches with their row and box, and short notes the read made about the photo. |
products | One row per product as read: brand, name, front-row facings, visibleUnits, estimatedUnits and confidence. |
realogram | Every 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. |
priceTags | Each shelf-edge tag: box, text, price, currency, itemCode, isPromo, and the matchedFacingIds it sits under. |
posm | Each 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. |
actions | The fix-first list: priority (1 first), type (restock, fix_orientation, fix_condition …), facingId or row, and a short reason. |
count | Null: count reads are not offered. |
judgmentStatus, warnings | ok; 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.jpgStatus codes
200A JPEG.404not_found, orno_image: only a completed read has one.503shelf_busy: try again shortly.

DELETE /shelf/reads/{readId}
Deletes the read: the photo, the marked-up photo and the result are erased first, then the read.
Status codes
204Deleted.404not_found.409read_busy: the read is still being read.503shelf_busy: nothing changed; send it again.
Errors
| Status | What it means | What to do |
|---|---|---|
400 | bad_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. |
401 | No valid bearer token. | Sign in again: the DocSpry Shelf app sends the token for you. |
402 | Not 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. |
404 | not_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. |
409 | read_busy: the read is still being read, so it cannot be deleted yet. | Wait until it has ended, then delete it. |
413 | too_large: the photo is larger than 20 MB. | Send a smaller photo. A phone photo of one shelf section is plenty. |
415 | unsupported_type: the photo is not a JPEG, PNG or WebP image. | Send a JPEG, PNG or WebP photo. |
429 | Today’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. |
503 | shelf_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
| Call | Price |
|---|---|
POST /shelf/reads | 200 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 route | Free |
- 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.