This directory contains the OpenAPI specification and documentation for the Yemaya API.
Contents#
openapi.json- OpenAPI 3.1.0 specification in JSON formatopenapi.yaml- OpenAPI specification in YAML format (generated)webhooks.md- Comprehensive webhook documentationexamples.md- Code examples in multiple programming languageserrors.md- Error codes reference (RFC 7807 Problem Details)changelog.md- API changelog and version historyrate-limits.md- Rate limiting policies and best practicessdk.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#
pnpm openapi:generate
This generates both openapi.json and openapi.yaml in this directory.
Validate OpenAPI Spec#
pnpm openapi:validate
Code Generation#
Generate client code from the OpenAPI specification:
# 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)#
curl -H "Authorization: Bearer <your_token>" https://api.yemaya.io/v1/projects
Obtain a token via /v1/auth/login.
API Key#
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 allowedX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Reset timestamp
Error Handling#
All errors follow this format:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human readable message",
"details": {}
}
}
Common error codes:
INVALID_CREDENTIALS- Invalid email/passwordUNAUTHORIZED- Missing or invalid tokenFORBIDDEN- Insufficient permissionsNOT_FOUND- Resource not foundVALIDATION_ERROR- Invalid request dataRATE_LIMITED- Too many requestsINTERNAL_ERROR- Server error
Pagination#
List endpoints support pagination:
GET /v1/projects?page=2&limit=20
Response includes metadata:
{
"data": [...],
"meta": {
"page": 2,
"limit": 20,
"total": 150,
"totalPages": 8,
"hasMore": true
}
}
Webhooks#
See webhooks.md for detailed webhook documentation.
SDKs#
Official SDKs are available for:
Support#
- Email: api@yemaya.io
- Documentation: https://docs.yemaya.io
- Status: https://status.yemaya.io