# ShareBrain API Documentation
# Complete developer guide for integrating AI agents

## 📋 Overview

ShareBrain provides a REST API with OpenAI-compatible endpoints for integrating 100+ specialized AI agents. This documentation covers authentication, endpoints, request/response formats, error handling, and code examples.

**Base URL**: https://sharebrains.net/api/v1
**Alternative URL**: https://sharebrains.net/v1

## 🔑 Authentication

All API requests require authentication using a Bearer token in the Authorization header:

```
Authorization: Bearer sb-your-api-key-here
```

### Getting Your API Key

1. Visit the Developer Portal: https://sharebrains.net/api-portal
2. Sign in with your ShareBrain account
3. Generate a new API key (keys start with "sb-")
4. Copy and securely store your API key

### Rate Limits

- **100 requests per hour** per API key
- Rate limit headers included in all responses
- Exceeded limits return HTTP 429 with retry-after header

## 🚀 Quick Start

### Step 1: List Available Agents

```bash
curl -X GET https://sharebrains.net/api/v1/agents \
  -H "Authorization: Bearer sb-your-api-key-here"
```

**Response:**
```json
{
  "object": "list",
  "data": [
    {
      "id": "48",
      "object": "agent",
      "name": "Spanish Language Tutor",
      "description": "Expert Spanish teacher for all levels",
      "category": "Language Teachers",
      "model": "gpt-4o",
      "created": 1688888888,
      "voice_enabled": true,
      "status": "active"
    }
  ]
}
```

### Step 2: Chat with an Agent

```bash
curl -X POST https://sharebrains.net/api/v1/agents/48/completions \
  -H "Authorization: Bearer sb-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello! How are you?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'
```

**Response:**
```json
{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "¡Hola! I'm doing great! Ready to help you learn Spanish?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}
```

## 📚 API Endpoints

### 1. List Agents

**Endpoint:** `GET /v1/agents`

**Description:** Get a list of all available AI agents

**Headers:**
- `Authorization: Bearer sb-your-api-key`

**Response:** List of agent objects with id, name, description, category, model, etc.

---

### 2. Get Agent Details

**Endpoint:** `GET /v1/agents/{agent_id}`

**Description:** Retrieve detailed information about a specific agent including system prompt and configuration

**Parameters:**
- `agent_id` (path) - The unique identifier of the agent

**Headers:**
- `Authorization: Bearer sb-your-api-key`

**Response:** Detailed agent object with system prompt, configuration, capabilities

---

### 3. Chat with Agent (Completions)

**Endpoint:** `POST /v1/agents/{agent_id}/completions`

**Description:** Send a message to an agent and receive a response. OpenAI-compatible format.

**Parameters:**
- `agent_id` (path) - The unique identifier of the agent

**Headers:**
- `Authorization: Bearer sb-your-api-key`
- `Content-Type: application/json`

**Request Body:**
```json
{
  "messages": [
    {"role": "user", "content": "Your message here"}
  ],
  "temperature": 0.7,      // Optional: 0.0 to 1.0, default 0.7
  "max_tokens": 500        // Optional: max response length
}
```

**Response:** OpenAI-compatible chat completion object with choices, usage stats

---

### 4. Generate Speech (Text-to-Speech)

**Endpoint:** `POST /v1/agents/{agent_id}/speech`

**Description:** Convert text to speech using the agent's voice settings. Returns audio/mpeg.

**Parameters:**
- `agent_id` (path) - The unique identifier of the agent

**Headers:**
- `Authorization: Bearer sb-your-api-key`
- `Content-Type: application/json`

**Request Body:**
```json
{
  "text": "Text to convert to speech",
  "voice_type": "alloy",      // Optional: alloy, echo, fable, onyx, nova, shimmer
  "voice_model": "tts-1"       // Optional: tts-1, tts-1-hd
}
```

**Response:** Audio file (audio/mpeg) with custom headers

**Response Headers:**
- `Content-Type: audio/mpeg`
- `X-Agent-Id: 48`
- `X-Voice-Type: alloy`
- `X-Voice-Model: tts-1`
- `X-Response-Time-Ms: 1234`

---

### 5. Get Usage Statistics

**Endpoint:** `GET /v1/usage`

**Description:** Check your API usage and rate limit status

**Headers:**
- `Authorization: Bearer sb-your-api-key`

**Response:** Usage statistics including request count, rate limit info

---

## 🎨 Features

### OpenAI Compatible
- Drop-in replacement for OpenAI API
- Same request/response format
- Works with existing OpenAI client libraries

### LLM.txt Protocol
- Standardized AI-to-AI communication protocol
- Each agent has a public llm.txt file
- No authentication required for llm.txt files

### Voice & TTS
- Text-to-speech with 6 voice options
- Two quality levels: tts-1 and tts-1-hd
- Audio caching for instant playback

### Security
- SHA256 key hashing
- Rate limiting (100 req/hour)
- Comprehensive error handling
- GDPR-compliant data handling

## 🤖 LLM.txt Protocol

The LLM.txt protocol is like "robots.txt for AI" - it tells other AI systems how to interact with ShareBrain agents.

### Access Agent LLM.txt Files

**No authentication required:**
```
https://sharebrains.net/api/agents/{agent_id}/llm.txt
```

**Example:**
```
https://sharebrains.net/api/agents/48/llm.txt
```

### What's in an LLM.txt File?

- Agent name, description, and category
- Capabilities (voice, memory, languages)
- Access information (public chat URL, API access requirements)
- Integration instructions
- Rate limits and usage guidelines

### Root LLM.txt

For platform-wide information and quick links:
```
https://sharebrains.net/llm.txt
```

## ⚠️ Error Handling

All errors follow a structured format:

```json
{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": "error_code",
    "param": null
  }
}
```

### Common Error Types

**authentication_error (HTTP 401)**
- Invalid or missing API key
- Expired API key
- Malformed Authorization header

**rate_limit_error (HTTP 429)**
- Rate limit exceeded (100 req/hour)
- Check retry-after header for wait time

**validation_error (HTTP 400)**
- Invalid request parameters
- Missing required fields
- Malformed JSON

**not_found_error (HTTP 404)**
- Agent not found
- Invalid endpoint

**server_error (HTTP 500)**
- Internal server error
- Try again later or contact support

## 💻 Code Examples

### JavaScript / Node.js

**Chat with Agent:**
```javascript
const response = await fetch('https://sharebrains.net/api/v1/agents/48/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb-your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello!' }],
    temperature: 0.7,
    max_tokens: 500
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

**Generate Speech:**
```javascript
const response = await fetch('https://sharebrains.net/api/v1/agents/48/speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb-your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hola! ¿Cómo estás?',
    voice_type: 'nova',
    voice_model: 'tts-1-hd'
  })
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
const audio = new Audio(audioUrl);
audio.play();
```

### Python

**Chat with Agent:**
```python
import requests

response = requests.post(
    'https://sharebrains.net/api/v1/agents/48/completions',
    headers={
        'Authorization': 'Bearer sb-your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [{'role': 'user', 'content': 'Hello!'}],
        'temperature': 0.7,
        'max_tokens': 500
    }
)

data = response.json()
print(data['choices'][0]['message']['content'])
```

**Generate Speech:**
```python
import requests

response = requests.post(
    'https://sharebrains.net/api/v1/agents/48/speech',
    headers={
        'Authorization': 'Bearer sb-your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'text': 'Hola! ¿Cómo estás?',
        'voice_type': 'nova',
        'voice_model': 'tts-1-hd'
    }
)

# Save audio to file
with open('speech.mp3', 'wb') as f:
    f.write(response.content)

print('Audio saved to speech.mp3')
```

### cURL Examples

**List Agents:**
```bash
curl -X GET https://sharebrains.net/api/v1/agents \
  -H "Authorization: Bearer sb-your-api-key"
```

**Chat:**
```bash
curl -X POST https://sharebrains.net/api/v1/agents/48/completions \
  -H "Authorization: Bearer sb-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello!"}]}'
```

**Generate Speech:**
```bash
curl -X POST https://sharebrains.net/api/v1/agents/48/speech \
  -H "Authorization: Bearer sb-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","voice_type":"alloy"}' \
  --output speech.mp3
```

## 🌐 Agent Categories

ShareBrain offers 100+ specialized agents across these categories:

- **Language Teachers**: 50+ languages with native tutors
- **Customer Support**: Automated support agents
- **Personal Assistants**: Task management and scheduling
- **Content Creation**: Writing, editing, brainstorming
- **Technical Support**: Code help and debugging
- **Business & Finance**: Analysis and planning
- **Healthcare & Wellness**: Health coaching and advice
- **Education & Learning**: Tutoring and skill development

## 🔗 Additional Resources

### For Developers

- **Developer Portal**: https://sharebrains.net/api-portal (get API keys)
- **API Documentation (Web)**: https://sharebrains.net/api-docs (this page)
- **API Documentation (Text)**: https://sharebrains.net/api-docs.txt (AI-friendly)
- **OpenAPI Spec**: https://sharebrains.net/openapi.json (Swagger/programmatic)
- **Agent Directory**: https://sharebrains.net/directory (browse all agents)

### For AI Systems

- **Root LLM.txt**: https://sharebrains.net/llm.txt (platform overview)
- **Agent LLM.txt**: https://sharebrains.net/api/agents/{agent_id}/llm.txt (per-agent)
- **OpenAPI Spec**: https://sharebrains.net/openapi.json (API discovery)
- **Sitemap**: https://sharebrains.net/sitemap.xml (all public pages)

### Integration Guides

- **API Integration Guide**: See API_INTEGRATION_GUIDE.md in documentation
- **Authentication Setup**: Available in developer portal
- **Rate Limiting**: 100 requests per hour per key
- **Best Practices**: Follow OpenAI-compatible patterns

## 📊 Usage Tips

### Best Practices

1. **Cache responses** when appropriate to save API calls
2. **Use appropriate temperature** (0.0 for deterministic, 0.7-1.0 for creative)
3. **Set max_tokens** to control response length
4. **Handle errors gracefully** with retry logic
5. **Monitor rate limits** in response headers

### Rate Limit Headers

All responses include rate limit information:
- `X-RateLimit-Limit`: Total requests allowed per hour
- `X-RateLimit-Remaining`: Requests remaining in current window
- `X-RateLimit-Reset`: Timestamp when limit resets

### Voice Best Practices

- Use `tts-1` for faster, lower quality (good for real-time)
- Use `tts-1-hd` for higher quality (good for final output)
- Choose voice type based on agent personality
- Cache audio responses when possible

## 🆘 Support

- **Platform**: ShareBrain
- **Website**: https://sharebrains.net
- **Developer Portal**: https://sharebrains.net/api-portal
- **Status**: Active and maintained

---

*Last Updated: 2025-11-04*
*API Version: 1.0*
*For AI systems and developers integrating with ShareBrain*

---

## Note for AI Web Scrapers

This is the plain text version of our API documentation, specifically formatted for AI tools, web scrapers, and automated systems. For the interactive web version with visual formatting, visit https://sharebrains.net/api-docs

All endpoints, examples, and integration guides above are current and actively maintained.