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

# Arx API Reference

> Complete reference for the Arx run-time defence REST API

## Overview

Arx is Fabraix's run-time defence layer for AI agents, informed by what our offensive agent [Nyx](/api-reference/nyx/introduction) finds in the wild. The premise is simple: you can't verify what you haven't tried to break, and the same research that makes Nyx effective on offence is what makes Arx effective on defence.

Arx provides three primary capabilities:

* **Session tracking**: register agent runs and correlate every step under a `trace_id`
* **Event logging**: record user inputs, model outputs, tool calls, memory ops, and environment events
* **Action checks**: validate actions in the context of the full session before they execute

## Base URL

All API requests should be made to:

```
https://api.fabraix.com/v1
```

## Authentication

All requests must include your API key in the `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://api.fabraix.com/v1/endpoint
```

See the [Authentication guide](/essentials/authentication) for details.

## Available Endpoints

<CardGroup cols={1}>
  <Card title="POST /register-agent-run" icon="play" href="/api-reference/arx/endpoint/register-agent-run">
    Register a new agent session and receive a trace\_id for tracking all subsequent events
  </Card>

  <Card title="POST /event" icon="list" href="/api-reference/arx/endpoint/event">
    Log events throughout your agent's reasoning loop for observability and analysis
  </Card>

  <Card title="POST /check" icon="shield-check" href="/api-reference/arx/endpoint/check">
    Validate actions before execution to prevent malicious or unintended behavior
  </Card>
</CardGroup>

## Request Format

All POST requests should use JSON format with `Content-Type: application/json`:

```json theme={null}
{
  "field1": "value1",
  "field2": "value2"
}
```

## Response Format

All successful responses return JSON with appropriate HTTP status codes:

```json theme={null}
{
  "result_field": "value",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

## Error Handling

Errors return appropriate HTTP status codes with detailed error messages:

```json theme={null}
{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": "ERROR_CODE"
  }
}
```

### Common Status Codes

| Status | Description                              |
| ------ | ---------------------------------------- |
| 200    | Success                                  |
| 400    | Bad Request - Invalid parameters         |
| 401    | Unauthorized - Invalid API key           |
| 403    | Forbidden - Insufficient permissions     |
| 404    | Not Found - Invalid endpoint or resource |
| 429    | Too Many Requests - Rate limit exceeded  |
| 500    | Internal Server Error                    |

## Rate Limits

API rate limits depend on your API key type:

| Key Type    | Requests/Minute | Requests/Hour |
| ----------- | --------------- | ------------- |
| Development | 60              | 1,000         |
| Production  | 600             | 10,000        |
| Enterprise  | Custom          | Custom        |

## SDK Support

Arx is currently consumed via the REST API directly. Official Arx SDKs are coming soon.

<Note>
  Looking for the **Nyx** CLI? See the [Nyx API reference](/api-reference/nyx/introduction). The `@fabraix/nyx` npm package is generally available today.
</Note>

## Pagination

For endpoints that return lists (future releases), pagination is handled via query parameters:

* `limit`: Number of items to return (max 100)
* `offset`: Number of items to skip
* `cursor`: Cursor for cursor-based pagination

Example:

```
GET /v1/events?limit=20&offset=40
```

## Versioning

The API version is included in the URL path. The current version is `v1`.

Breaking changes will result in a new API version. Non-breaking changes may be added to the current version.

## Webhooks (Coming Soon)

Future releases will support webhooks for real-time notifications:

* Action blocked events
* Anomaly detection alerts
* Session completion notifications

## Support

Need help with the API?

* 📧 Email: [founders@fabraix.com](mailto:founders@fabraix.com)
* 📖 GitHub: [Report API issues](https://github.com/fabraix/api/issues)
* 💬 Discord: [Join our developer community](https://discord.gg/n4scEY9NF6)

## Quick Start Examples

<CardGroup cols={2}>
  <Card title="Register a Session" icon="rocket">
    ```bash theme={null}
    curl -X POST https://api.fabraix.com/v1/register-agent-run \
      -H "x-api-key: YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"agent_id": "123", "timestamp": "2024-01-01T00:00:00Z", "system_prompt": "Helper"}'
    ```
  </Card>

  <Card title="Log an Event" icon="pencil">
    ```bash theme={null}
    curl -X POST https://api.fabraix.com/v1/event \
      -H "x-api-key: YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"trace_id": "abc", "type": "user", "content": "{}", "schema": "{}"}'
    ```
  </Card>

  <Card title="Check an Action" icon="shield">
    ```bash theme={null}
    curl -X POST https://api.fabraix.com/v1/check \
      -H "x-api-key: YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"trace_id": "abc", "content": "{}", "schema": "{}"}'
    ```
  </Card>

  <Card title="Handle Errors" icon="exclamation">
    ```python theme={null}
    try:
        response = client.check_action(...)
    except RateLimitError as e:
        time.sleep(e.retry_after)
        response = client.check_action(...)
    ```
  </Card>
</CardGroup>