Requests and CORS

Base URL and versioning

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:

Content-Type: application/json

For uploads:

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.

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:

Authenticates your user.
Authorizes the specific file.
Calls Everabyte server-side.
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:

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.

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.

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

Base URL and versioning

Required headers

Browser requests are not supported

Timeouts

Retries

Backoff

Compression and binary bodies

Proxy and TLS inspection

Response parsing

​Base URL and versioning

​Required headers

​Browser requests are not supported

​Timeouts

​Retries

​Backoff

​Compression and binary bodies

​Proxy and TLS inspection

​Response parsing

Base URL and versioning

Required headers

Browser requests are not supported

Timeouts

Retries

Backoff

Compression and binary bodies

Proxy and TLS inspection

Response parsing