borkoldocs

Getting Started

Introduction

What the Borkol storefront API is, its base URL and versioning, and a three-step quickstart.

View as Markdown

The Borkol storefront API is the public HTTP API of the Borkol commerce platform. It gives you programmatic, read and write access to a single store (a tenant): its product catalog, stock levels, customers, orders, and custom objects. You use it to build custom storefronts, headless frontends, mobile apps, and server-side integrations against a Borkol store.

The API is a conventional JSON-over-HTTPS API. Every request and response body is JSON. Authentication is a tenant API key sent as a bearer token. There are no cookies, no sessions, and no OAuth flows on the storefront API.

Base URL

All requests go to:

text
https://api.borkol.com

The API is versioned in the URL path. The current and only version is v1, so every route in this documentation starts with /v1. Authenticated storefront routes live under /v1/api/...; the only unauthenticated route is the health check at /v1/ping.

Module surfaces mount under /v1/api/{module}:

ModuleMount point
Commerce/v1/api/commerce (plus /v1/api/commerce/configurator)
Stock/v1/api/stock
Customers/v1/api/customers
Objects/v1/api/objects

A module surface is only reachable when that module is enabled for your store. Calling a route of a disabled module returns 403 {"error": "Module not enabled: {key}"}. See Errors and rate limits for the full error catalog.

Authentication in one line

Every /v1/api request carries a tenant API key as a bearer token:

text
Authorization: Bearer {api_key}

The key identifies the store, so no other tenant header is needed. Merchants create keys in the client dashboard (app.borkol.com) under Settings > API keys. Each key carries a set of scopes (for example commerce:read) that control which endpoints it may call. The full details are on the Authentication page.

Conventions

These hold across the whole API:

  • Resource IDs are UUID strings (API key IDs, which only appear in the merchant dashboard flow, are integers).
  • Money values are integers in minor units (cents) with a separate ISO 4217 currency field. 15900 with "currency": "EUR" means EUR 159.00.
  • Timestamps are ISO 8601 strings.
  • List endpoints use the pagination envelope documented once in Errors and rate limits. The fundamentals endpoints on these pages (/v1/ping, /v1/api/me) return bare JSON objects with no wrapper.

Quickstart

Three requests take you from nothing to your first catalog call.

Step 1: verify connectivity. /v1/ping needs no credentials and confirms the base URL and API version are reachable.

Request
curl https://api.borkol.com/v1/ping
Response
{
  "status": "ok",
  "version": "v1"
}

Step 2: verify your API key. Create a key in the client dashboard (Settings > API keys) with at least the commerce:read scope, then call /v1/api/me. It returns the store the key belongs to and the scopes the key carries. This endpoint requires no scope, only a valid key.

Request
curl https://api.borkol.com/v1/api/me \
  -H "Authorization: Bearer {api_key}"
Response
{
  "tenant": {
    "id": "9c4e7f0a-2b31-4d6e-8f0a-1d2c3b4a5e6f",
    "name": "Example Store",
    "slug": "example-store"
  },
  "scopes": ["tenant:read", "commerce:read"]
}

Step 3: fetch the catalog. With a key that carries commerce:read, list products from the commerce module. This request fails with 403 {"error": "Module not enabled: commerce"} if the commerce module is not enabled for the store, and with 403 {"message": "Invalid ability provided."} if the key lacks the commerce:read scope.

Request
curl https://api.borkol.com/v1/api/commerce/products \
  -H "Authorization: Bearer {api_key}"

The response is a paginated product list; the product endpoints are documented in the Commerce chapter.

Where to go next

  • Authentication: API keys, scopes, the /v1/api/me endpoint, and tenant suspension.
  • Errors and rate limits: every error envelope, the 422 validation shape, rate limiting, and the pagination envelope.
  • Webhooks: event-driven notifications for orders and stock changes.