API Overview

Tula provides a RESTful API that enables programmatic access to the load balancer's configuration and operational data. The API allows you to automate provisioning, integrate with CI/CD pipelines, build custom dashboards, and manage Tula appliances at scale without relying on the web interface.

Base URL

All API requests are made over HTTPS to the Tula appliance's management address:

https://<appliance-ip>/api/v1/

The API is versioned via the URL path. The current stable version is v1. Future versions will be introduced at new path prefixes (e.g., /api/v2/) while maintaining backward compatibility on existing versions for the duration of their support lifecycle.

Authentication

Every API request must include a valid API key. Keys are generated and managed through the Tula web interface. Include the key in the Authorization header using the Bearer scheme:

Authorization: Bearer <your-api-key>

Alternatively, you can pass the key as a query parameter using ?api_key=<your-api-key>, though the header method is preferred for security. See the API Authentication guide for details on key generation, permissions, and rotation.

Request and Response Format

The API accepts and returns JSON exclusively. All request bodies must use Content-Type: application/json, and all responses are returned with Content-Type: application/json.

A typical successful response follows this structure:

{
  "status": "success",
  "data": { ... }
}

Error responses include a status, an error code, and a human-readable message:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'port' field is required."
  }
}

HTTP status codes follow standard conventions: 200 for successful reads, 201 for successful resource creation, 400 for validation errors, 401 for authentication failures, 403 for authorization failures, 404 for resources not found, and 429 for rate-limited requests.

Available Endpoints

The API provides endpoints organized around the core resources of the Tula platform:

Each endpoint supports standard HTTP methods: GET for retrieval, POST for creation, PUT for full updates, PATCH for partial updates, and DELETE for removal. Detailed endpoint documentation with request parameters, response schemas, and examples is provided in the individual API reference pages.

Rate Limiting

The API enforces rate limits to protect appliance resources and ensure consistent performance. The default limit is 60 requests per minute per API key. Rate limit status is communicated via response headers:

• X-RateLimit-Limit -- Maximum requests allowed per window.
• X-RateLimit-Remaining -- Requests remaining in the current window.
• X-RateLimit-Reset -- Unix timestamp when the current window resets.

When the rate limit is exceeded, the API returns a 429 Too Many Requests response. Implement exponential backoff in your client to handle rate limiting gracefully.

Pagination

Endpoints that return collections support pagination via page and per_page query parameters. The default page size is 25 items. Pagination metadata is included in the response:

{
  "status": "success",
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 142
  }
}

Next Steps

To begin using the API, generate an API key by following the API Authentication guide.