> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# BRX API Reference

Welcome to the BRX API reference documentation. This comprehensive guide provides detailed information about the BRX API endpoints, request/response formats, authentication methods, and error handling.

## Overview

The BRX API allows you to programmatically interact with the BRX platform, enabling you to create, manage, and execute BRKs (BRX Knowledge Representations). With this API, you can:

* Create, update, delete, and clone BRKs
* List and search for BRKs
* Execute BRKs with custom inputs
* Validate BRKs to ensure they are properly structured
* Manage access control for BRKs
* Generate and manage API keys

## Base URL

All API requests should be made to the following base URL:

```
https://api.brx.ai
```

For testing and development purposes, you can use the staging environment:

```
https://staging-api.brx.ai
```

## Authentication

The BRX API supports two authentication methods:

### Firebase Authentication

For web applications and client-side code, you can use Firebase Authentication. Include the Firebase ID token in the `Authorization` header:

```
Authorization: Bearer <firebase-id-token>
```

### API Key Authentication

For server-to-server communication, you can use API keys. Include your API key in the `key` header:

```
key: <your-api-key>
```

You can generate API keys using the [Generate API Key](#tag/API-Key-Management/operation/generateApiKey) endpoint.

## Error Handling

The BRX API uses conventional HTTP response codes to indicate the success or failure of an API request:

* `200 OK`: The request was successful
* `400 Bad Request`: The request was malformed or missing required parameters
* `401 Unauthorized`: Authentication credentials are missing or invalid
* `403 Forbidden`: The authenticated user does not have permission to access the requested resource
* `404 Not Found`: The requested resource does not exist
* `429 Too Many Requests`: The user has exceeded the rate limit
* `500 Internal Server Error`: An unexpected error occurred on the server

All error responses include a JSON object with the following structure:

```json theme={null}
{
  "httpResponse": {
    "isError": true,
    "errorID": "error-id",
    "statusMsg": "Error message"
  }
}
```

## Rate Limiting

The BRX API implements rate limiting to ensure fair usage and prevent abuse. Rate limits vary by endpoint and authentication method. If you exceed the rate limit, you will receive a `429 Too Many Requests` response.

## Pagination

Endpoints that return lists of resources support pagination through the `limit` and `offset` parameters:

* `limit`: Maximum number of resources to return (default: 10, max: 100)
* `offset`: Number of resources to skip (default: 0)

The response includes the total number of resources and the current limit and offset values.

## Versioning

The BRX API is versioned to ensure backward compatibility. The current version is `v1`. The version is included in the URL path:

```
https://api.brx.ai/v1
```

## OpenAPI Specification

The complete OpenAPI specification for the BRX API is available in [JSON format](/api-reference/openapi.json).

## API Endpoints

The BRX API is organized into the following categories:

### BRK Management

Endpoints for creating, updating, and managing BRKs:

* [Get BRK Schema](/api-reference/endpoint/get): Fetches a BRK schema by its ID
* [Modify BRK](/api-reference/endpoint/create): Creates, updates, deletes, or clones a BRK
* [List BRKs](/api-reference/endpoint/list): Lists all BRKs accessible to the authenticated user
* [List Private BRKs](/api-reference/endpoint/list-private): Lists all private BRKs accessible to the authenticated user
* [Get Raw BRK](/api-reference/endpoint/raw): Retrieves the raw data for a BRK

### BRK Execution

Endpoints for executing and validating BRKs:

* [Execute BRK](/api-reference/endpoint/execute): Executes a BRK with the provided input values
* [Validate BRK](/api-reference/endpoint/validate): Validates a BRK to ensure it is properly structured

### Access Control

Endpoints for managing access control to BRKs:

* [Update BRK ACL](/api-reference/endpoint/update-acl): Updates the access control list for a BRK
* [Check BRK ACL](/api-reference/endpoint/check-acl): Retrieves the access control list for a BRK

### API Key Management

Endpoints for managing API keys:

* [Generate API Key](/api-reference/endpoint/generate-key): Generates a new API key
* [List API Keys](/api-reference/endpoint/list-keys): Lists all API keys for the authenticated user
* [Delete API Key](/api-reference/endpoint/delete-key): Deletes an API key