API Reference

The Ordinaut REST API is the primary interface for all interactions with the task scheduling system. It is built with FastAPI, which provides automatic, interactive documentation.

Interactive Documentation

While this reference provides a comprehensive overview, you can also use the interactive documentation generated by the API itself:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

These interfaces allow you to explore and test every endpoint directly from your browser.

Base URL

• Development: http://localhost:8080
• Production: https://api.your-domain.com/v1

Common Concepts

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses follow a consistent JSON format, as defined by the ErrorResponse schema:

{
  "error": "ValidationError",
  "message": "Invalid schedule expression",
  "details": {
    "field": "schedule_expr",
    "value": "invalid cron",
    "expected": "Valid cron expression (e.g., '0 9 * * 1-5')"
  },
  "request_id": "req-123456789",
  "timestamp": "2025-01-10T10:00:00Z"
}

Rate Limiting

To ensure system stability, the API enforces rate limits. By default, this is based on the client's IP address. If you exceed the rate limit, you will receive a 429 Too Many Requests response. Check the Retry-After header to know when you can send another request.

The response body will also contain details:

{
  "error": "RateLimitExceeded",
  "message": "Too many requests",
  "details": {
    "limit": "60/minute"
  },
  "retry_after": 45
}