# API Reference

> Complete endpoint documentation for the ForbocAI SDK API

<div>
  ÁPI_Réference // Éndpoint_Dócs
</div>

<div>
  ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ
</div>

The ForbocAI SDK API provides RESTful endpoints for managing AI agents, local inference, memory, and more. This reference documents all available endpoints.

***

## Base URL

<div>
  Báse_ÚRL // Cónnect
</div>

```
Production: https://api.forbocai.com/v1
Local Dev:  http://localhost:3001/v1
```

***

## Authentication

<div>
  Áuth_Módule // Béarer_Tóken
</div>

API requests require a bearer token in the Authorization header:

```bash
curl -X POST https://api.forbocai.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cortexId": "ctx_abc123", "persona": "A helpful assistant"}'
```

***

## API Categories

<div>
  Módulátion_Máp // Sýstem_Óverview
</div>

<CardGroup cols={2}>
  <Card title="Cortex" icon="duotone brain">
    Initialize and manage local SLM inference engines
  </Card>

  <Card title="Agents" icon="duotone robot">
    Create, interact with, and manage autonomous AI entities
  </Card>

  <Card title="Memory" icon="duotone database">
    Store and recall semantic memories for agents
  </Card>

  <Card title="Bridge" icon="duotone bridge">
    Validate AI actions against game rules
  </Card>

  <Card title="Soul" icon="duotone ghost">
    Export and import portable agent state
  </Card>

  <Card title="Ghost" icon="duotone flask">
    Run automated QA testing with headless agents
  </Card>
</CardGroup>

<div>
  ᛭ ᛫ ᛬ ᛫ ᛭
</div>

***

## Response Format

<div>
  Respónse_Schéma // JSÓN_Fórmat
</div>

All API responses follow a consistent JSON format:

```json
{
  "id": "agt_123abc",
  "object": "agent",
  "created": 1706572800,
  "data": { ... }
}
```

***

## Error Handling

<div>
  Érror_Códes // Fáulт_Státus
</div>

Errors return appropriate HTTP status codes with details:

```json
{
  "error": {
    "code": "ITEM_NOT_IN_INVENTORY",
    "message": "Agent does not possess the item 'legendary_sword'",
    "details": {
      "item": "legendary_sword",
      "agentInventory": ["rusty_key", "healing_potion"]
    }
  }
}
```

| Status Code | Description                              |
| ----------- | ---------------------------------------- |
| `200`       | Success                                  |
| `201`       | Created                                  |
| `202`       | Accepted (async operation started)       |
| `400`       | Bad Request (invalid parameters)         |
| `401`       | Unauthorized (missing/invalid token)     |
| `404`       | Not Found                                |
| `422`       | Unprocessable Entity (validation failed) |
| `500`       | Internal Server Error                    |

***

## Rate Limits

<div>
  Ráte_Límit // Thróttling
</div>

| Tier       | Requests/minute | Concurrent Agents |
| ---------- | --------------- | ----------------- |
| Free       | 60              | 3                 |
| Pro        | 600             | 25                |
| Enterprise | Unlimited       | Unlimited         |

***

## SDKs

<div>
  SDK_Lïbraries // Instáll
</div>

Official SDK libraries wrap this API for common platforms:

```bash
# JavaScript/TypeScript
npm install forbocai

# Python
pip install forbocai

# Rust
cargo add forbocai
```

<div>
  ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ
</div>