Quickstart

This quickstart takes you from zero to a verified upload. It assumes you can sign in to the Everabyte dashboard with a company account.

Every credential below is a placeholder. Export real values in your shell or secret manager; never commit them.

1. Confirm your workspace type

The REST API is for company workspaces. If you sign in with an individual EverSpark account, API-key requests return:

{
  "status": 403,
  "message": "API keys are available for company accounts only.",
  "data": null,
  "code": "API_COMPANY_ONLY"
}

If that happens, use a company workspace or contact support. The message text is illustrative; branch on the code.

2. Create an API key

Create the key from the dashboard’s API key area for your company. Key creation is a dashboard action, not a public REST endpoint. When you create the key:

Choose the scopes your integration needs. Start read-only, then add writes.
Restrict the key to specific buckets if the integration does not need the whole company.
Set an expiry appropriate to the integration. The dashboard default is 90 days.
Copy the secret immediately. The secret is not retrievable later.

The credentials look like this:

Public key: pk_<64 hexadecimal characters>
Secret key: sk_<64 hexadecimal characters>

Store them as environment variables:

export EVB_PUBLIC_KEY="pk_your_public_key"
export EVB_SECRET_KEY="sk_your_secret_key"

Use a separate key per application and per environment. When a key leaks, revoke that one key instead of rotating every integration.

3. Note your bucket ID

Every file and folder call is scoped to a bucket. You can discover the buckets your key can reach with the API, or copy the identifier from the dashboard:

curl "https://api.everabyte.io/api/buckets/all" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"

Each item in data carries a bucket id, its name, and the opaque datacenterId location binding. A key restricted to specific buckets lists only those buckets.

export EVB_BUCKET_ID="00000000-0000-0000-0000-000000000000"

If the list is empty and the dashboard shows no bucket, ask an administrator to create one; bucket creation is not available to API keys. See Buckets.

4. Verify authentication

List the folders in that bucket:

curl "https://api.everabyte.io/api/folders/findAll/$EVB_BUCKET_ID?page=1&limit=10" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"

An illustrative success response:

{
  "status": 200,
  "message": "No folders found.",
  "data": {
    "total": 0,
    "page": 1,
    "totalPages": 1,
    "limit": 10,
    "data": []
  }
}

An empty list is a valid result: it means the bucket has no root folders yet. A 401 means the key pair is wrong; a 403 means the key does not cover this bucket or lacks a scope.

5. List files in a bucket

curl "https://api.everabyte.io/api/files/findAll/$EVB_BUCKET_ID?page=1&limit=10" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"

The list is paginated; see Pagination.

6. Upload a file

Uploads use multipart/form-data. The file field name is not significant: the API reads every file part in the request.

curl -X POST "https://api.everabyte.io/api/files/upload/$EVB_BUCKET_ID" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY" \
  -F "file=@./report.pdf"

To place the file inside a folder, add the folder ID to the path:

curl -X POST "https://api.everabyte.io/api/files/upload/$EVB_BUCKET_ID/FOLDER_ID" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY" \
  -F "file=@./report.pdf"

An illustrative response:

{
  "status": 200,
  "message": "File uploaded",
  "data": {
    "file": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "report",
      "extFile": "pdf"
    },
    "fileId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "effectiveFolderId": null,
    "fileSize": 482133,
    "sizeBytes": 482133,
    "versionId": "3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo",
    "scheme": "hybrid-v1",
    "encryption": "SSE",
    "isUpdate": false
  }
}

Upload requires active encryption keys for the owning user context. If they are missing or incomplete, the request fails before any file is stored. Do not retry blindly; fix the key state first.

7. Download the file

curl -L "https://api.everabyte.io/api/files/FILE_ID/stream" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY" \
  --output ./report.pdf

The download response is binary. Useful response headers include X-File-Id, X-File-Name, X-File-Size, X-File-Extension, and X-Encryption: SSE. Range requests are supported.

8. Clean up

Soft-delete the file you uploaded:

curl -X DELETE "https://api.everabyte.io/api/files/delete/FILE_ID?trash=soft" \
  -H "X-Public-Key: $EVB_PUBLIC_KEY" \
  -H "X-Secret-Key: $EVB_SECRET_KEY"

Soft-deleted files remain restorable during the trash display window. Hard deletion is permanent. See Manage file lifecycle.

Troubleshooting the first request

Symptom	Likely cause	Fix
`401` with no `code`	Missing or invalid key pair	Check both headers and that the key is active
`403 API_COMPANY_ONLY`	Key belongs to an individual account	Use a company key
`403 API_KEY_SURFACE_DENIED`	Route is outside the storage surface	Use a documented storage endpoint
`403 API_BUCKET_SCOPE_DENIED`	Key is restricted to other buckets	Use an allowed bucket or widen the key
`402 SUBSCRIPTION_REQUIRED`	No active subscription	Renew billing in the dashboard
`403 TRIAL_API_LIMIT_REACHED`	Trial quota exhausted	Upgrade or wait for the quota window
`429 API_KEY_RATE_LIMITED`	Per-key request rate exceeded	Back off and retry later

Next steps

Read API keys before production.
Read Scopes and permissions to apply least privilege.
Read Upload files for multipart limits and safe processing.

Getting Started

Core Concepts

Authentication & Security

Storage Guides

Error Handling

Security & Data Protection

Enterprise & Partners

Resources

1. Confirm your workspace type

2. Create an API key

3. Note your bucket ID

4. Verify authentication

5. List files in a bucket

6. Upload a file

7. Download the file

8. Clean up

Troubleshooting the first request

Next steps

​1. Confirm your workspace type

​2. Create an API key

​3. Note your bucket ID

​4. Verify authentication

​5. List files in a bucket

​6. Upload a file

​7. Download the file

​8. Clean up

​Troubleshooting the first request

​Next steps

1. Confirm your workspace type

2. Create an API key

3. Note your bucket ID

4. Verify authentication

5. List files in a bucket

6. Upload a file

7. Download the file

8. Clean up

Troubleshooting the first request

Next steps