API Reference

Here you can find all you need to know about the exposed API endpoints of the BSH Engine.

API Endpoints

Authentication

All protected API endpoints require authentication. See Authentication API for JWT Bearer, cookie sessions, API keys, and refresh behavior.

Authorization: Bearer {{accessToken}}

API keys use the same header name with the raw key: Authorization: bsh_… (not Bearer).

Response Format

All API responses follow a consistent JSON format:

{
  "data": [],
  "timestamp": 1234567890,
  "code": 200,
  "status": "OK",
  "meta": {}
}

Response meta

Pagination

Pagination is supported for all endpoints that return a list of items.

{
  "data": [],
  "timestamp": 1234567890,
  "code": 200,
  "status": "OK",
  "meta": {},
  "pagination": {
    "current": 1,
    "total": 20,
    "pages": 2,
    "first": true,
    "last": false
  }
}

Error Handling

Errors are returned with appropriate HTTP status codes and error details:

{
  "data": [],
  "timestamp": 1234567890,
  "code": 400,
  "status": "ERROR STATUS",
  "meta": {
    "sql": "<SQL query>",
    "tips": {}
  },
  "error": "<Error message>"
}

the meta.sql is the SQL query that was executed to get the error.
the meta.tips is a list of tips to help you fix the error.

Validation Errors

Validation errors are returned as an object with the field name and the error message.
this error is offen sent when you try to insert or update data with invalid data.

{
  "data": [],
  "timestamp": 1234567890,
  "code": 400,
  "status": "ERROR STATUS",
  "meta": {
    "sql": "<SQL query>",
    "tips": {},
  },
  "error": "<Error message>",
  "validations": [
    {
      "field": "<Field name>",
      "error": "<Error message>"
    }
  ]
}