Using the API

API version: v1 Estimated reading time: 8 minutes Audience: Integrators and backend developers

This guide covers the practical conventions for calling Booga Enterprise REST APIs: how to construct requests, what responses look like, and how to handle pagination, errors, and rate limits. For the full endpoint contract (paths, parameters, response schemas), use the interactive API reference as the authoritative source.

Base URL

APIs are served from a dedicated API hostname for each environment:

Environment	Base URL
Production	https://api.boogaenterprise.com
Beta	https://beta-api.boogaenterprise.com

All endpoint paths in this documentation and in the OpenAPI specs are relative to the base URL. For example, listing files is GET https://api.boogaenterprise.com/api/files/.

Request Format

All requests use standard HTTP methods and JSON payloads:

Method	Usage
GET	Retrieve resources or collections
POST	Create a resource or trigger an action
PUT	Full replacement of a resource
PATCH	Partial update of a resource
DELETE	Remove a resource

Required Headers

Header	Value	When
Authorization	Bearer <api_key> or X-API-Key: <api_key>	Every authenticated request
Content-Type	application/json	Requests with a JSON body (POST, PUT, PATCH)
Accept	application/json	Recommended on all requests

You can pass your API key in either the Authorization: Bearer <key> header or the X-API-Key: <key> header — both are accepted. See the Authentication guide for details.

Example Request

GET /api/files/ HTTP/1.1
Host: api.boogaenterprise.com
Authorization: Bearer bge_a1b2c3d4e5f6...
Accept: application/json

Example Response

{
  "count": 42,
  "next": "https://api.boogaenterprise.com/api/files/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": "f8c1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "name": "Q4-Report.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-15T10:30:00Z"
    }
  ]
}

Tenancy

Every API request is scoped to the tenant that owns the API key. You do not need to pass a tenant identifier explicitly — the middleware resolves the tenant from the authenticated key and applies it automatically. All queries, resource creation, and permission checks are tenant-isolated.

If your key's scopes grant access to organisation-level resources, you may pass an organisation identifier where the endpoint supports it (see the API reference for per-endpoint parameters).

Pagination

List endpoints return paginated results using limit/offset pagination:

Parameter	Type	Default	Description
limit	integer	20	Number of results per page (1–100)
offset	integer	0	Number of results to skip

The response envelope for paginated endpoints:

{
  "count": 150,
  "next": "https://api.boogaenterprise.com/api/files/?limit=20&offset=20",
  "previous": null,
  "results": [ ... ]
}

• count — total number of results matching the query
• next — URL for the next page (null if on the last page)
• previous — URL for the previous page (null if on the first page)
• results — array of resource objects for the current page

To iterate through all pages, follow the next URL until it returns null.

Filtering and Search

Many list endpoints support filtering via query parameters. Common patterns:

Parameter	Example	Description
search	?search=quarterly	Free-text search across relevant fields
ordering	?ordering=-created_at	Sort by field; prefix with - for descending
created_after	?created_after=2026-01-01	Filter by creation date
status	?status=active	Filter by resource status

Exact filtering parameters vary by endpoint. Consult the API reference for the filters each endpoint supports.

Error Handling

The API uses standard HTTP status codes and returns structured error bodies:

Status Codes

Code	Meaning
200	Success
201	Resource created
204	Success with no content (e.g., after DELETE)
400	Bad request — invalid parameters or payload
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid credentials but insufficient permissions or scopes
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Error Response Format

{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied"
}

For validation errors (400), the response body maps field names to error messages:

{
  "name": ["This field is required."],
  "email": ["Enter a valid email address."]
}

Rate Limit Errors

When you exceed your API key's rate limit, the API returns 429 Too Many Requests with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Limit-Hour: 3600
X-RateLimit-Remaining-Hour: 3542

Best practice is to implement exponential backoff when receiving 429 responses. Check the X-RateLimit-Remaining-* headers proactively to avoid hitting the limit.

Rate Limits

Each API key has configurable rate limits:

Window	Default	Configurable
Per minute	60 requests	Yes — set when creating or editing the key
Per hour	3,600 requests	Yes — set when creating or editing the key

Rate limits are enforced per API key, not per IP address. If you need higher throughput, adjust the limits in the API Management console or create additional keys for different workloads.

Rate-limit status is returned in response headers on every request (see Request Flow for the full header list).

Idempotency

POST requests that create resources are generally not idempotent — submitting the same request twice creates two resources. To avoid duplicates, implement client-side deduplication or check for existing resources before creating.

PUT and PATCH requests are idempotent — applying the same update multiple times produces the same result.

Versioning

The API does not use URL-based versioning (e.g., /v1/, /v2/). Instead, the API evolves with backward-compatible changes:

• New fields may be added to response objects — your client should ignore unknown fields
• New endpoints may be added — existing endpoints are not removed without deprecation
• Deprecated endpoints are flagged in the API Endpoint Registry and OpenAPI schema before removal

The api_version field in this documentation tracks the narrative docs revision. The info.version in the OpenAPI schema tracks the published API contract.

OpenAPI Schema

You can obtain the full OpenAPI 3.0.3 specification programmatically:

GET /api/api-management/openapi-schema/ HTTP/1.1
Host: api.boogaenterprise.com
Authorization: Bearer <your_api_key_or_session>

Optional query parameters:

Parameter	Description
plugin	Filter the schema to a specific plugin (e.g., files, chat)
include_plugins	Comma-separated list of plugins to include (default: all)

The schema is cached for one hour. Import it into Postman, Insomnia, or any OpenAPI-compatible tool.

SDKs

Generate client libraries from the API Management console or via the SDK endpoint:

GET /api/api-management/generate-sdk/?language=python HTTP/1.1
Host: api.boogaenterprise.com
Authorization: Bearer <your_api_key>

Supported languages: python, typescript, javascript, curl, postman. Add &download=zip to receive a ZIP archive.

Generated SDKs handle authentication, provide typed request/response objects, and include usage examples.

Related Topics

• Architecture Overview — how the platform components fit together
• Authentication & Authorization — API keys, scopes, and security
• Integration Getting Started — build your first integration step by step
• Webhooks & Events — subscribe to platform events
• API Reference — interactive OpenAPI documentation for every endpoint

Related Topics

• Architecture Overview
• Authentication & Authorization
• Integration Getting Started

---

⏱️ Read time: 8 minutes | 📊 Difficulty: beginner