Documentation
Public API

API Usage

Authentication

Most API endpoints require authentication. Before calling the various endpoints, you must have obtained an access token authorizing you to access the user's data (see the authentication section).

Required Headers

Each HTTP call to the API must include the following two headers:

Without these two pieces of information, access to the API will be denied.
  • Access token: obtained after user authentication
    Authorization: Bearer <access_token>
  • Client ID: obtained by registering your API client at https://account.diapstash.com
    DS-API-CLIENT-ID: <client_id>

Data Format

Data is returned in JSON format. It is included in the data parameter of the response object. Other parameters contain information about pagination or sorting used.

Response Example

{
  "page": 1,
  "size": 20,
  "count": 20,
  "totalCount": 150,
  "data": [...]
}

Filters

You can filter your calls according to several criteria depending on the resources. Filters are used as query params. Depending on the field type, you have several options.

Strings / Enums

<field>.equals
string
The value is equal to the filter value
<field>.not
string
The value is not equal to the filter value
<field>.in
string
The value is included in one of the filter values (can be used multiple times, ?<field>.in=1&<field.in=2&<field.in=3>)
<field>.notIn
string
The value is not included in the filter values (can be used multiple times, ?field.notIn=1&field.notIn=2&field.notIn=3)

Dates

<field>.equals
date
The date is equal to the filter date
<field>.not
date
The date is not equal to the filter date
<field>.lt
date
The date is strictly less than the filter date
<field>.lte
date
The date is less than or equal to the filter date
<field>.gt
date
The date is strictly greater than the filter date
<field>.gte
date
The date is greater than or equal to the filter date

Numbers

<field>.equals
number
The value is equal to the filter value
<field>.not
number
The value is not equal to the filter value
<field>.lt
number
The value is strictly less than the filter value
<field>.lte
number
The value is less than or equal to the filter value
<field>.gt
number
The value is strictly greater than the filter value
<field>.gte
number
The value is greater than or equal to the filter value

Lists

<field>.equals
array
The list is strictly equal to all filter values (can be used multiple times: ?<field>.hasSome=1&<field.hasSome=2&<field.hasSome=3>)
<field>.has
any
The list contains at least the filter value
<field>.hasEvery
array
The list contains all filter values (can be used multiple times ?<field>.hasEvery=1&<field.hasEvery=2&<field.hasEvery=3>)
<field>.hasSome
array
The list contains at least one of the filter values (can be used multiple times: ?<field>.hasSome=1&<field.hasSome=2&<field.hasSome=3>)
<field>.isEmpty
boolean
The list is empty

Pagination

The entire API uses the pagination principle. Data is returned in batches.

Query Parameters

The following query params allow you to control pagination:

size
number required
Size of each data batch (min: 1, max: 50)
page
number required
Page number of the data to retrieve (min: 1)

Response

Each call returns the following information:

  • page: page number obtained
  • size: number of data items requested
  • count: number of data items returned (for the last page, there may be fewer data items than requested)
  • totalCount: total number of available data items
  • data: array containing the requested data

Data Sorting

Depending on the endpoints, you can sort the data to retrieve. Sorting can be ascending or descending, on one or more fields.

Usage

Sorting is done via the sort query param. You must indicate the field name and the order (asc or desc) separated by a comma.

Example: ?sort=createdAt,desc

Multi-criteria Sorting

For sorting on multiple fields, add the sort query param multiple times.

Example: ?sort=category,asc&sort=createdAt,desc

Each call returns a sort parameter containing the sorting applied to the request.

Error Handling

When an error occurs, the API returns a JSON response with the following structure. The name field can be used to programmatically identify the specific error type.

{
  "status": 401,
  "message": "No Cloud-Sync linked",
  "name": "NO_CLOUD_SYNC_LINKED",
  "type": "HTTP_EXCEPTION"
}

400 — BAD_REQUEST

Meaning: The DS-API-CLIENT-ID header is missing from the request.

Solution: Ensure every request includes the DS-API-CLIENT-ID header with your registered client ID.

401 — UNAUTHORIZED — Invalid client

Meaning: The client ID in the DS-API-CLIENT-ID header does not match the one embedded in the access token, or the client does not exist.

Solution: Verify that your client ID is correct and that the access token was obtained for this specific client.

401 — UNAUTHORIZED — Invalid user

Meaning: The user referenced in the access token could not be found.

Solution: Ask the user to re-authenticate and obtain a fresh access token.

401 — UNAUTHORIZED — No scopes / Unallowed scope

Meaning: The client has no valid scopes configured, or the scope required by the endpoint is not permitted for this client.

Solution: Review your client configuration in the DiapStash Account portal and ensure the required scopes are enabled.

401 — NO_CLOUD_SYNC_LINKED

Meaning: The user has no cloud sync linked to their account.

Solution: Without cloud sync, you cannot access their data. Ask the user to configure a cloud sync in their DiapStash account settings.

403 — FORBIDDEN — Insufficient scopes

Meaning: You are attempting to access a resource that requires a scope (permission) that was not approved by the user during authentication.

Solution: Ask the user to re-authorize the application with the necessary scopes, or adjust your request to only use authorized resources.

429 — Too Many Requests

Meaning: You have exceeded the rate limit of 120 requests per hour. The quota is applied per authenticated user, or per IP address for unauthenticated requests.

Solution: Back off and retry after the window resets. Check the RateLimit response header for the remaining seconds before the window resets (w field). See the Rate limits section for details on headers and recommendations.

Rate limits

The API is rate limited to 120 requests per hour per user. If the API call is made with valid authentication, the quota is applied per user. If the call does not have authentication, the quota is applied per IP address.

The limit window is started after the first (user) request, and it will be reset to zero after 60 minutes. During this period, you can make a maximum of 120 API requests.

If you exceed the limit, you will receive a 429 Too Many Requests error.

Headers

The API returns the following headers in response to rate limiting (based on ratelimit headers draft 8):

  • RateLimit-Policy : To get the maximum requests per time window you are allowed
    q
    number
    Count of allowed calls during the window
    w
    number
    Number of seconds of the rate limit window
  • RateLimit : The remaining count during the period
    r
    number
    Remaining request count that can be used during the current window
    w
    number
    Number of seconds before the window resets

Recommendations

  • Cache catalog data in your app to avoid massive API calls.
  • You don't need to check every minute for history or stock changes. In general, there are several hours between each change.
  • Sort in descending order on createdAt or updatedAt fields to get the latest items.