# SerenAI

> Pay Per Call Agentic Commerce for public and private data

SerenAI provides serverless Postgres databases with pay-per-query access for AI agents. Agents can discover and query publisher databases using SerenBucks micropayments.

## Quick Links

- [API Documentation](https://docs.serendb.com/)
- [MCP Server](https://docs.serendb.com/mcp/)
- [Getting Started](https://docs.serendb.com/guides/quickstart)

## Core Concepts

- **Projects**: Isolated database environments with branching support
- **Branches**: Git-like database branching for dev/prod isolation
- **Endpoints**: Compute instances that serve database connections
- **Publishers**: Data providers in the agent marketplace
- **SerenBucks**: Prepaid credits for pay-per-query access (1 SB = $1 USD)

## Authentication

All API requests require authentication via API key:

```
Authorization: Bearer seren_live_xxxxx
```

## Base URL

```
https://api.serendb.com
```

## Key Endpoints

### Projects
- `POST /projects` - Create a new project
- `GET /projects` - List all projects
- `GET /projects/{project_id}` - Get project details
- `DELETE /projects/{project_id}` - Delete a project

### Branches
- `POST /projects/{project_id}/branches` - Create branch
- `GET /projects/{project_id}/branches` - List branches
- `GET /projects/{project_id}/branches/{branch_id}` - Get branch details

### SQL Execution
- `POST /projects/{project_id}/branches/{branch_id}/sql` - Execute SQL query
- `POST /projects/{project_id}/branches/{branch_id}/sql/transaction` - Execute SQL transaction

### Agent Marketplace
- `GET /agent/publishers` - List available data publishers
- `POST /agent/publishers` - Create a new publisher (API key auth)
- `GET /agent/publishers/{slug}` - Get publisher details
- `POST /agent/query` - Execute paid query against publisher
- `GET /agent/balance` - Check SerenBucks balance
- `POST /agent/deposit` - Deposit SerenBucks via Stripe checkout

### Endpoints (Compute)
- `POST /projects/{project_id}/branches/{branch_id}/endpoints` - Create endpoint
- `GET /projects/{project_id}/branches/{branch_id}/endpoints` - List endpoints
- `POST /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}/start` - Start endpoint
- `POST /projects/{project_id}/branches/{branch_id}/endpoints/{endpoint_id}/suspend` - Suspend endpoint

## Response Format

All responses are JSON. Successful responses include the requested data. Errors follow this format:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human readable message"
  }
}
```

## Rate Limits

- Standard: 100 requests/minute
- SQL execution: 60 queries/minute
- Agent marketplace: Pay-per-query (no artificial limits)

## Optional

- [Full API Reference](/llms-full.txt)
- [MCP Tool Schemas](/mcp/tools.json)
- [OpenAPI Specification](https://api.serendb.com/openapi.json)