Eve library

Yemaya API Documentation

Other

Revision 1

On this page

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 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