API reference
API reference
Base URL: https://api.boxlatvia.lv. All paths below start with /v1. Requests and responses are JSON, except picture uploads (multipart) and the token request (form).
#Areas
LocationsThe places where your boxes are: address, district, map position and amenities.BoxesStorage units with prices, sizes and stock. Submit them for review when they are ready.PicturesUpload and manage pictures of your boxes and locations.Reference dataThe codes for amenities, districts, price units and sizes that your requests use.Supplier profileRead and update your company details, and check which credentials you are using.
#All endpoints
| Endpoint | Scope | What it does | |
|---|---|---|---|
| GET | /v1/locations | locations:read | List locations — Your locations, oldest first, one page at a time. |
| POST | /v1/locations | locations:write | Create a location — Creates a location. Only name is required: you can fill the rest in step by step; missing tells you what is left. |
| GET | /v1/locations/{id} | locations:read | Retrieve a location — One location. The response carries the ETag you need to change or delete it. |
| PATCH | /v1/locations/{id} | locations:write | Update a location — Changes only the fields you send. external_id can be set once and then never changes. |
| PUT | /v1/locations/by-external-id/{external_id} | locations:write | Create or update by your own id — Creates the location if your id is new, otherwise updates the fields you send. No If-Match is needed: meant for feeds that should win. |
| DELETE | /v1/locations/{id} | locations:write | Delete a location — Deletes the location and its pictures. Refused while it still has boxes. |
| GET | /v1/boxes | boxes:read | List boxes — Your boxes, oldest first, one page at a time. |
| POST | /v1/boxes | boxes:write | Create a box — Creates a box as a DRAFT. It needs a name and a location; the rest can follow. |
| GET | /v1/boxes/{id} | boxes:read | Retrieve a box — One box, with the ETag you need to change or delete it. |
| PATCH | /v1/boxes/{id} | boxes:write | Update a box — Changes only the fields you send, including stock (available_units) and prices. Changes to a published box are visible on the website straight away. |
| PUT | /v1/boxes/by-external-id/{external_id} | boxes:write | Create or update by your own id — Creates the box if your id is new (then name and a location are required), otherwise updates the fields you send. No If-Match: ideal for stock and price feeds. |
| POST | /v1/boxes/{id}/submit | boxes:write | Submit for review — Asks BoxLatvia to review and publish the box (DRAFT → REVIEW). The API never publishes: BoxLatvia staff do. |
| POST | /v1/boxes/{id}/withdraw | boxes:write | Withdraw — Takes the box out of review or off the website and back to DRAFT. A draft stays a draft (200). |
| DELETE | /v1/boxes/{id} | boxes:write | Delete a box — Deletes the box and its pictures. A box that has orders cannot be deleted: set available_units to 0 to stop new bookings. |
| GET | /v1/boxes/{id}/images | boxes:read | List pictures — The pictures of a box, oldest first. |
| POST | /v1/boxes/{id}/images | images:write | Upload pictures — Uploads up to 5 pictures at once as multipart/form-data, one part named file per picture. |
| DELETE | /v1/boxes/{id}/images/{image_id} | images:write | Delete a picture — Deletes the picture and its file. Deleting a box or a location deletes its pictures too. |
| GET | /v1/reference/{kind} | reference:read | List reference data — The codes you use in other requests. Each row has a stable code: use it, never the Latvian name or the id. The lists are short and rarely change: fetch them once a day at most. |
| GET | /v1/me | supplier:read | Who am I — The credentials you are calling with, their scopes, and your supplier profile. The first call to make to check that everything works. |
| GET | /v1/supplier | supplier:read | Retrieve your profile — Your company record, with the ETag needed to change it. |
| PATCH | /v1/supplier | supplier:write | Update your profile — Changes contact and address fields. The registration number, person type and anything commercial are managed by BoxLatvia and cannot be changed here. |
| POST | /v1/oauth/token | no scope needed | Get an access token — OAuth 2.0 client credentials: exchange your client id and secret for a bearer token valid for 15 minutes. |
#Service endpoints
These need no credentials.
| Endpoint | What it does | |
|---|---|---|
| GET | /v1/health | Liveness check. Returns {"status":"ok"}. No credentials needed. |
| GET | /v1/openapi.json | This API as an OpenAPI 3.1 document, for code generators and tools such as Postman. No credentials needed. |
| GET | /v1/.well-known/jwks.json | The public keys that sign access tokens. No credentials needed. |
#Conventions
- Authentication: Basic or Bearer. Each endpoint lists the scope it needs.
- Conditional updates, safe retries, dry runs and pagination work the same everywhere.
- Errors are problem details with a
request_id. - Machine-readable: OpenAPI 3.1.