API Reference

The Turqoa REST API provides programmatic access to all platform capabilities, including gate transactions, security events, maritime data, drone operations, and system configuration. All endpoints return JSON and follow consistent conventions.

Base URL

All API requests are made to:

https://api.turqoa.com/v1

For on-premise deployments, replace with your instance URL:

https://turqoa.yourcompany.com/api/v1

Authentication

Every request must include a valid API key or OAuth 2.0 bearer token in the Authorization header:

curl https://api.turqoa.com/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for details on API keys, OAuth 2.0, and scoped permissions.

Rate Limits

Rate limits are applied per API key and vary by plan:

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1712398800

When rate limited, the API returns 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "retry_after": 12
  }
}

Response Format

All successful responses follow this structure:

{
  "data": { },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-06T10:00:00Z"
  }
}

Paginated responses include pagination metadata:

{
  "data": [ ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-06T10:00:00Z"
  },
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_items": 1234,
    "total_pages": 25,
    "has_next": true,
    "has_previous": false
  }
}

Pagination Parameters

Error Handling

Errors follow a consistent structure across all endpoints:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid date format for 'start_date'. Expected ISO 8601.",
    "details": [
      {
        "field": "start_date",
        "message": "Expected format: YYYY-MM-DDTHH:MM:SSZ"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Error Codes

Available Endpoints

Gate Transactions

See Gate Transactions.

Events

See Events.

Webhooks

See Webhooks.

Maritime

Drone Operations

System

SDKs

Official SDKs are available for:

from turqoa import TurqoaClient

client = TurqoaClient(api_key="your_api_key")
events = client.events.list(severity="high", limit=10)

import { TurqoaClient } from "@turqoa/sdk";

const client = new TurqoaClient({ apiKey: "your_api_key" });
const events = await client.events.list({ severity: "high", limit: 10 });