API Overview

Torale provides a REST API for programmatic access to all platform functionality.

Base URL

https://api.torale.ai

Interactive API Documentation

For interactive API exploration with detailed request/response schemas:

• OpenAPI Documentation (ReDoc) - Full API reference with schemas
• OpenAPI Specification (JSON) - Machine-readable API spec

Try It Out

The ReDoc interface provides detailed examples and schema information for every endpoint.

Authentication

All authenticated requests require an API key or Clerk JWT in the Authorization header:

curl -H "Authorization: Bearer sk_..." \
  https://api.torale.ai/api/v1/tasks

Generate API keys at torale.ai/settings/api-keys.

Core Endpoints

Tasks

POST   /api/v1/tasks                       # Create task
GET    /api/v1/tasks                       # List user's tasks
GET    /api/v1/tasks/{id}                  # Get task (public or owned)
PUT    /api/v1/tasks/{id}                  # Update task
DELETE /api/v1/tasks/{id}                  # Delete task
PATCH  /api/v1/tasks/{id}/visibility       # Toggle public/private
POST   /api/v1/tasks/{id}/execute          # Execute immediately
POST   /api/v1/tasks/{id}/fork             # Fork a public task

Executions & Notifications

GET    /api/v1/tasks/{id}/executions       # Execution history
GET    /api/v1/tasks/{id}/notifications    # Filtered: condition met only
GET    /api/v1/notifications/sends         # Notification send history

Public Tasks (no auth required)

GET    /api/v1/public/tasks                        # Discover public tasks
GET    /api/v1/public/tasks/id/{task_id}            # Get public task by UUID

Authentication & User Management

POST   /auth/sync-user                     # Sync Clerk user to DB
GET    /auth/me                            # Current user info
POST   /auth/mark-welcome-seen             # Mark welcome flow seen
POST   /auth/api-keys                      # Generate API key
GET    /auth/api-keys                      # List API keys
DELETE /auth/api-keys/{id}                 # Revoke API key

Users

GET    /api/v1/users/username/available     # Check username availability
PATCH  /api/v1/users/me/username            # Set username

Email Verification

POST   /api/v1/email-verification/send           # Send verification code
POST   /api/v1/email-verification/verify          # Verify email with code
GET    /api/v1/email-verification/verified-emails  # List verified emails
DELETE /api/v1/email-verification/verified-emails/{email}  # Remove verified email

Waitlist (public)

POST   /public/waitlist                    # Join waitlist (no auth)

Response Format

Responses use JSON. Most endpoints return the resource directly:

{
  "id": "uuid",
  "field": "value",
  "created_at": "2025-01-15T10:30:00Z"
}

List endpoints like GET /api/v1/tasks return a bare JSON array:

[
  { "id": "uuid-1", "name": "Task 1", ... },
  { "id": "uuid-2", "name": "Task 2", ... }
]

Some public task endpoints wrap results with metadata:

{
  "tasks": [...],
  "total": 100,
  "offset": 0,
  "limit": 20
}

Error Handling

Errors follow standard HTTP status codes with detail messages:

{
  "detail": "Error description"
}

Validation errors (422) include field-level details:

{
  "detail": [
    {
      "loc": ["body", "search_query"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Rate Limits

Public endpoints have per-IP rate limits:

• Public tasks: 10 requests/minute
• Vanity URL lookups: 20 requests/minute
• Waitlist join: 5 requests/minute

Next Steps

• Read Authentication for API key setup
• View Tasks API for task management endpoints
• Check Error Handling for error codes