> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbofiles.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

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

<CodeGroup>
  ```bash Request theme={null}
  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}'
  ```

  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

## 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`:

```json theme={null}
{
  "jsonapi": {
    "version": "1.1"
  },
  "errors": [
    {
      "code": "401",
      "detail": "Max file size exceeded",
      "title": "Bad Request"
    }
  ]
}
```