Skip to main content
The TurboFiles API implements the JSON:API specification, ensuring a consistent and predictable response structure across all endpoints.

​
Response Structure

Every successful response includes a top-level data field containing either a single resource object or an array of resource objects. Each resource object comprises:
  • type: Identifies the resource category (e.g., files, tasks)
  • id: Unique identifier for the resource
  • attributes: Object containing the resource’s core data
  • relationships (optional): Defines connections to other resources
  • links (optional): Provides related URLs
  • meta (optional): Contains supplementary information

​
Example

curl "https://api.turbofiles.api/v1/tasks" \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {api_key}'

{
  "jsonapi": {
    "version": "1.1"
  },
  "data": [
    {
      "type": "tasks",
      "id": "<string>",
      "attributes": {
        "public": false,
        "created_at": "2023-01-01T00:00:00.000000Z",
        "updated_at": "2023-01-02T00:00:00.000000Z",
        "settings": {},
        "format": {
          "input": "image/png",
          "output": "image/webp"
        }
        "started_at": "2023-01-03T00:00:00.000000Z",
        "processed_at": "2023-01-04T00:00:00.000000Z",
        "processing_metadata": {},
        "status": "COMPLETED"
      },
      "relationships": {
        "input": {
          "data": {
            "type": "files",
            "id": "<string>"
          },
          "links": {
            "self": "<string>",
            "related": "<string>"
          }
        },
        "output": {
          "data": {
            "type": "files",
            "id": "<string>"
          },
          "links": {
            "self": "<string>",
            "related": "<string>"
          }
        }
      },
      "links": {
        "self": "<string>",
        "download": "<string>"
      }
    }
  ],
  "included": [
    {
      "type": "files",
      "id": "8fhd83jpk",
      "attributes": {
        "format": "image/png",
        "size": 504233,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "links": {
        "self": "<string>",
        "upload": "<string>",
        "download": "<string>"
      }
    }
  ],
  "links": {
    "prev": "<string>",
    "next": "<string>"
  },
  "meta": {
    "rangeTruncated": true
  }
}

​
Error Handling

The API uses standard HTTP status codes to indicate request outcomes:
  • 2xx: Success
  • 4xx: Client-side errors (e.g., missing parameters, failed actions)
  • 5xx: Server-side errors (rare)
For 4xx errors, the response includes a JSON:API-compliant errors array. Each error object provides detailed information through fields like detail, status, and title: 
{
  "jsonapi": {
    "version": "1.1"
  },
  "errors": [
    {
      "code": "401",
      "detail": "Max file size exceeded",
      "title": "Bad Request"
    }
  ]
}