> ## 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.

# Requests and CORS

> Request format, browser limitations, timeouts, and safe retry behavior.

## Base URL and versioning

```text theme={null}
https://api.everabyte.io/api
```

Every documented route is relative to this base. The API is served over HTTPS only. This reference does not document a version prefix beyond `/api`; treat undocumented behavior as unstable and re-check the pages you depend on when you upgrade.

## Required headers

| Header | Value |
| - | - |
| `X-Public-Key` | `pk_...` |
| `X-Secret-Key` | `sk_...` |

For JSON requests:

```http theme={null}
Content-Type: application/json
```

For uploads:

```http theme={null}
Content-Type: multipart/form-data; boundary=...
```

Do not set `Content-Type: application/json` on a multipart upload. Let your HTTP client generate the boundary.

## Browser requests are not supported

The API's CORS policy does not allow the `X-Public-Key` and `X-Secret-Key` headers. A browser `fetch` with those headers triggers a preflight `OPTIONS` request that the API does not approve, so the actual request never runs.

This is intentional: embedding a company secret in a browser would expose it to every user of your application.

> [!WARNING]
>
> Do not try to work around this with a public proxy that injects credentials. That turns your key into an unauthenticated public API and is equivalent to leaking it.

If a browser needs file data, implement a backend endpoint that:

1. Authenticates your user.
2. Authorizes the specific file.
3. Calls Everabyte server-side.
4. Streams the result back without exposing credentials.

## Timeouts

Uploads and downloads can take much longer than a typical JSON call. Set timeouts by operation:

| Operation | Suggested client timeout |
| - | - |
| Bucket and folder reads | 10–30 seconds |
| File metadata reads | 10–30 seconds |
| Small uploads | 2–5 minutes |
| Large uploads | No fixed total timeout; use socket read/write timeouts |
| Downloads | No fixed total timeout; stream with a read timeout |

A total request timeout on a multi-gigabyte upload is a common cause of truncated transfers. Prefer per-socket inactivity timeouts over a hard total deadline.

## Retries

There is no documented idempotency-key mechanism. Retrying a non-idempotent write can duplicate work:

* Uploading twice can create a second version or a duplicate file.
* Copying twice creates two copies.
* Restoring twice may return a no-op or an error.

Retry rules:

| Operation type | Retry on network error? |
| - | - |
| `GET` | Yes, with backoff |
| `DELETE` | Carefully; check state first |
| `PUT` update | Yes only if the operation is naturally idempotent |
| `POST` upload, copy, move, restore | Only after verifying the previous attempt's outcome |

For uploads, verify by listing files or checking the expected `fileId` before re-sending a large payload.

## Backoff

Use exponential backoff with jitter. A practical policy:

```text theme={null}
base = 500 ms
factor = 2
max = 30 s
jitter = random(0, base)
```

Retry `429` and transient `5xx`. Do not retry `400`, `401`, `402`, `403`, or `410`.

## Compression and binary bodies

Do not assume the API compresses JSON responses. Do not compress upload bodies unless you control both ends; the API expects the file bytes as multipart parts.

Download responses are binary. If your HTTP client auto-decompresses based on `Content-Encoding`, ensure it also preserves byte counts correctly for your integrity checks.

## Proxy and TLS inspection

If you run an outbound proxy or TLS inspection appliance, verify that it:

* preserves both API key headers,
* does not buffer large upload or download bodies in memory,
* does not rewrite `Content-Length` or `Content-Range`,
* allows long-lived streaming responses.

Broken range handling is a frequent cause of corrupt downloads behind corporate proxies.

## Response parsing

Check the status code before parsing. Some errors have an `error` field, others have `code`. A successful response has `data`.

```ts theme={null}
const response = await fetch(url, { headers });

if (!response.ok) {
  const body = await response.json().catch(() => null);
  const code = body?.code;
  throw new ApiError(response.status, code, body?.message);
}

const body = await response.json();
return body.data;
```

Never branch on the human-readable message: it is localized and may change.


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