BReact OS API Reference

The BReact OS API provides a simple interface for interacting with our services. While the API handles kernel and system resources internally, you'll primarily work with the service endpoints. This reference covers authentication and usage of the service API.

API Overview

BReact OS exposes a RESTful API built on FastAPI, following modern API design principles:

• Standard HTTP methods (GET, POST)
• JSON request and response bodies
• Consistent error handling
• API key authentication
• Resource-based URL structure

Authentication

All API requests require authentication using an API key. For detailed information on authentication methods and best practices, refer to the Authentication Guide.

Base URL and Versioning

All API endpoints are prefixed with /api/v1/, following semantic versioning principles:

Response Format

All API responses follow a consistent structure:

Success Response

Error Response

Rate Limiting

API requests are subject to rate limiting. When limits are exceeded, the API returns a 429 Too Many Requests status code with information about the limit and when it resets.

Core Endpoints

Service Management

List Services

Returns a list of all registered services and their metadata.

Execute Service

Executes a specific service endpoint with the provided parameters.

Path Parameters:

• service_id - ID of the service to execute
• endpoint - Name of the endpoint to call

Request Body:

Service-specific parameters as JSON

Response:

Get Service Result

Retrieves the result of a previously executed service.

Path Parameters:

• process_id: ID of the process to retrieve results for

Query Parameters:

• access_token: Security token received when executing the service

Response (Completed): When a process has completed, the response contains the actual result and metadata:

Response (Pending): When a process is still running, the response indicates its pending status:

Note: Service results are automatically removed after 60 seconds to free up system resources. Make sure to retrieve and store results promptly.

Common Error Codes

The API may return the following error codes in response to requests:

• UNAUTHORIZED: Authentication failed due to invalid credentials
• MISSING_API_KEY: No API key was provided in the request
• BAD_REQUEST: The request was malformed or contained invalid parameters
• NOT_FOUND: The requested resource was not found
• RATE_LIMIT_EXCEEDED: The rate limit for API calls has been exceeded
• INSUFFICIENT_CREDITS: Your account has insufficient credits for this operation
• SERVICE_NOT_FOUND: The requested service does not exist or is not available

SDK Integration

For simplified API interactions, consider using the BReact OS SDK which provides:

• Type-safe client for all API endpoints
• Automatic authentication handling
• Streamlined error handling
• Async support