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

# Conventions

> Response envelopes, identifiers, content types, and the rules that hold across every documented endpoint.

## Content types

| Operation | Request | Response |
| - | - | - |
| JSON operations | `application/json` | `application/json` |
| Upload | `multipart/form-data` | `application/json` |
| File stream download | — | Binary with `Content-Type` from the stored file |

## Response envelopes

There is more than one envelope. Which one you receive depends on where the failure occurred.

### Controller success

```json theme={null}
{
  "status": 200,
  "message": "Files retrieved successfully",
  "data": {}
}
```

### Controller error

```json theme={null}
{
  "status": 400,
  "message": "Invalid input",
  "error": "Detailed reason"
}
```

Controller errors generally do **not** include a stable `code`.

### Middleware / guard error

```json theme={null}
{
  "status": 403,
  "message": "API key is not allowed to access this bucket",
  "data": null,
  "code": "API_BUCKET_SCOPE_DENIED"
}
```

Middleware errors carry a stable `code`. This is the shape to branch on for authorization and quota decisions.

### Framework error

Framework-level failures can surface as:

```json theme={null}
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```

In production, 5xx messages are sanitized. Do not depend on their text.

> [!TIP]
>
> Write one decoder that accepts all four shapes, then normalize into your own error type. Check `code` first, then `status`/`statusCode`, then `message`.

## HTTP status versus inner status

Most endpoints report HTTP status directly. Two areas are exceptions:

* **File restore** and **version operations** return HTTP `200` even when the underlying operation failed, and carry the failure inside `data.status`.
* **Folder restore** returns HTTP `200` with an explanatory message when the folder is not in trash.

Always inspect the body for these operations. Do not branch on HTTP status alone.

## Identifiers

| Identifier | Format | Notes |
| - | - | - |
| `bucketId` | UUID | Read from the bucket list, or copied from the dashboard |
| `folderId` | UUID | `null` means root in body fields; a missing path segment means the same on some routes |
| `fileId` | UUID | Authoritative file reference |
| `versionId` | Opaque string | Storage version identifier |
| `publicKey` | `pk_` + 64 hex | Not a secret |
| `secretKey` | `sk_` + 64 hex | Secret; shown once |

Path identifiers are UUIDs unless stated otherwise. Do not construct or guess them.

## File naming

* `name` is the display name **without** the extension.
* `extFile` is the lowercased extension **without** a leading dot.
* The reconstructed filename is `name + "." + extFile` when `extFile` is non-empty.

Do not assume `name` contains a dot or an extension.

## Timestamps

Timestamps are ISO 8601 strings. Treat them as UTC; do not assume a local offset.

## Null versus absent

* `null` is meaningful: for example, `effectiveFolderId: null` means the bucket root.
* An absent field means the information was not included, not that it is empty.

Do not normalize `null` to `""` or `0` in your own models.

## Empty success payloads

Some operations return `data: ""`. A file delete is the notable example. This is a success, not an error. Check the HTTP status and `message`, not the truthiness of `data`.

## Required scopes

Every documented operation lists the scope pair it needs. Storage operations require a bucket scope plus a resource scope:

* read: `buckets:read` + resource read scope
* write: `buckets:write` + resource write scope
* delete: `buckets:write` + resource delete scope

## Idempotency

No idempotency key header is documented. Retrying a write blindly can create duplicates or extra versions.

Safe retry guidance:

| Operation | Retry safe? |
| - | - |
| `GET` operations | Yes |
| Upload | Not blindly; check for the resulting file first |
| Move / copy | Not blindly; copy creates a new file |
| Delete | Effectively yes, but a second call may return `404` |
| Restore | Not blindly; state may have changed |

## Errors to retry

| Condition | Retry |
| - | - |
| `429` | Yes, with backoff |
| `5xx` | Yes, with backoff, bounded |
| `401`, `402`, `403` | No; fix the cause |
| `400`, `404`, `410`, `413` | No; fix the request or state |

## Related

> **[Pagination](https://docs.everabyte.com/api-reference/pagination.md)**
>
> List response shape.

> **[Errors](https://docs.everabyte.com/api-reference/errors.md)**
>
> Status codes and codes.

> **[Authentication](https://docs.everabyte.com/api-reference/authentication.md)**
>
> Headers.

> **[Playground](https://docs.everabyte.com/api-reference/playground.md)**
>
> Request display limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.