Skip to content

Requests

The base URL, the headers and the body rules every operation shares.

Version v1.1, updated

On this page

Every request goes to the API over https, with your API key and, for a write, a JSON body. This page lists what all operations expect, so the operation pages only state what is particular to them.

Base URL

Every path of this documentation starts with /v1 and goes after https://api.birp.io. Always use https.

Headers

Header

When

Value

Authorization

Every operation except GET /v1/openapi.json.

Bearer followed by your API key.

Content-Type

Every write that has a body.

application/json.

Idempotency-Key

Every POST. Optional on PUT, PATCH and DELETE.

A value unique to the request, such as a new UUID. See Idempotency.

Accept

Optional.

application/json. Errors come as application/problem+json.

POST /v1/categoriesHTTP
POST /v1/categories HTTP/1.1
Host: api.birp.io
Authorization: Bearer $BIRP_API_KEY
Content-Type: application/json
Idempotency-Key: <a new UUID for each request>

{"name": "Flour", "product_kind": "goods"}

Body

  • A write takes one JSON object. Reads and DELETE take no body.

  • A body may be up to 1 MB. A larger one answers 413 payload_too_large.

  • A body that is not valid JSON answers 400 invalid_json.

  • A body sent with another content type answers 415 unsupported_media_type.

  • A field the operation does not know answers 422 validation_failed, naming the field. So does a field that BIRP computes, such as a total.

Query parameters

Reads take their filters as query parameters, listed per resource in Pagination and filtering. An unknown parameter answers 422 validation_failed, so a typo never returns everything without a filter.

Related

  • responses
  • idempotency
  • formats
  • errors-overview