# Yemaya API Documentation

This directory contains the OpenAPI specification and documentation for the Yemaya API.

## Contents

- `openapi.json` - OpenAPI 3.1.0 specification in JSON format
- `openapi.yaml` - OpenAPI specification in YAML format (generated)
- `webhooks.md` - Comprehensive webhook documentation
- `examples.md` - Code examples in multiple programming languages
- `errors.md` - Error codes reference (RFC 7807 Problem Details)
- `changelog.md` - API changelog and version history
- `rate-limits.md` - Rate limiting policies and best practices
- `sdk.md` - SDK documentation and code generation guides

## Interactive Documentation

The API provides built-in interactive documentation:

### Swagger UI

Access Swagger UI at: `http://localhost:3000/docs`

Swagger UI provides:
- Interactive API exploration
- Try-it-out functionality
- Request/response examples
- Authentication testing

### Scalar API Reference

Access Scalar at: `http://localhost:3000/reference`

Scalar provides:
- Modern, clean interface
- Dark mode support
- Code samples in multiple languages
- Quick navigation
- Authentication configuration
- Search with hotkey (Cmd/Ctrl+K)

### API Playground

Access the playground at: `http://localhost:3000/playground`

The API Playground provides:
- Interactive endpoint testing
- Real-time request/response display
- Multiple HTTP client examples (cURL, JavaScript, Python, Go, etc.)
- Authentication helper
- Request history

## Generating Documentation

### Generate OpenAPI Spec

```bash
pnpm openapi:generate
```

This generates both `openapi.json` and `openapi.yaml` in this directory.

### Validate OpenAPI Spec

```bash
pnpm openapi:validate
```

## Code Generation

Generate client code from the OpenAPI specification:

```bash
# Generate TypeScript client
pnpm codegen typescript

# Generate Python client
pnpm codegen python

# Generate Go client
pnpm codegen go

# Generate all clients
pnpm codegen:all
```

Supported languages:
- TypeScript
- Python
- Go
- Ruby
- PHP
- Java
- C#

Generated code is output to `generated/<language>/`.

## API Endpoints

### Authentication

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/auth/login` | POST | Login with email/password |
| `/v1/auth/register` | POST | Register new account |
| `/v1/auth/refresh` | POST | Refresh access token |
| `/v1/auth/logout` | POST | Logout and invalidate session |
| `/v1/auth/oauth/{provider}` | GET | OAuth authentication |

### Users

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/users/me` | GET | Get current user profile |
| `/v1/users/me` | PATCH | Update current user profile |
| `/v1/users/{userId}` | GET | Get user by ID |

### Projects

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/projects` | GET | List projects |
| `/v1/projects` | POST | Create project |
| `/v1/projects/{projectId}` | GET | Get project |
| `/v1/projects/{projectId}` | PATCH | Update project |
| `/v1/projects/{projectId}` | DELETE | Delete project |

### Assets

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/projects/{projectId}/assets` | GET | List assets |
| `/v1/projects/{projectId}/assets` | POST | Create asset |
| `/v1/projects/{projectId}/assets/{assetId}` | GET | Get asset |
| `/v1/projects/{projectId}/assets/{assetId}` | PATCH | Update asset |
| `/v1/projects/{projectId}/assets/{assetId}` | DELETE | Delete asset |

### Scenes

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/projects/{projectId}/scenes` | GET | List scenes |
| `/v1/projects/{projectId}/scenes` | POST | Create scene |
| `/v1/projects/{projectId}/scenes/{sceneId}` | GET | Get scene |
| `/v1/projects/{projectId}/scenes/{sceneId}` | PATCH | Update scene |
| `/v1/projects/{projectId}/scenes/{sceneId}` | DELETE | Delete scene |

### Characters

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/projects/{projectId}/characters` | GET | List characters |
| `/v1/projects/{projectId}/characters` | POST | Create character |
| `/v1/projects/{projectId}/characters/{characterId}` | GET | Get character |
| `/v1/projects/{projectId}/characters/{characterId}` | PATCH | Update character |
| `/v1/projects/{projectId}/characters/{characterId}` | DELETE | Delete character |

### Capability Domains

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/capabilities/isis/{path}` | ALL | Proxy generation requests to Isis |
| `/v1/capabilities/sophia/{path}` | ALL | Proxy research requests to Sophia |
| `/v1/capabilities/hathor/{path}` | ALL | Proxy worldbuilding requests to Hathor |
| `/v1/capabilities/bellona/{path}` | ALL | Proxy engine and media-sync requests to Bellona |

### Webhooks

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/webhooks` | GET | List webhooks |
| `/v1/webhooks` | POST | Create webhook |
| `/v1/webhooks/{webhookId}` | GET | Get webhook |
| `/v1/webhooks/{webhookId}` | PATCH | Update webhook |
| `/v1/webhooks/{webhookId}` | DELETE | Delete webhook |
| `/v1/webhooks/{webhookId}/test` | POST | Test webhook |

### Health

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Basic health check |
| `/health/ready` | GET | Readiness check |
| `/health/live` | GET | Liveness check |

## Authentication

The API supports two authentication methods:

### Bearer Token (JWT)

```bash
curl -H "Authorization: Bearer <your_token>" https://api.yemaya.io/v1/projects
```

Obtain a token via `/v1/auth/login`.

### API Key

```bash
curl -H "X-API-Key: <your_api_key>" https://api.yemaya.io/v1/projects
```

Create API keys via `/v1/auth/api-keys`.

## Rate Limiting

- Authenticated requests: 1000/minute
- Unauthenticated requests: 60/minute

Rate limit headers:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Reset timestamp

## Error Handling

All errors follow this format:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  }
}
```

Common error codes:
- `INVALID_CREDENTIALS` - Invalid email/password
- `UNAUTHORIZED` - Missing or invalid token
- `FORBIDDEN` - Insufficient permissions
- `NOT_FOUND` - Resource not found
- `VALIDATION_ERROR` - Invalid request data
- `RATE_LIMITED` - Too many requests
- `INTERNAL_ERROR` - Server error

## Pagination

List endpoints support pagination:

```bash
GET /v1/projects?page=2&limit=20
```

Response includes metadata:

```json
{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasMore": true
  }
}
```

## Webhooks

See [webhooks.md](./webhooks.md) for detailed webhook documentation.

## SDKs

Official SDKs are available for:

- [TypeScript/JavaScript](../../packages/sdk-typescript)
- [Python](../../packages/sdk-python)
- [C++](../../packages/sdk-cpp)

## Support

- Email: api@yemaya.io
- Documentation: https://docs.yemaya.io
- Status: https://status.yemaya.io
