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

# Quickstart

> Create a company API key, verify access, and upload a file with the Everabyte REST API.

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

> [!NOTE]
>
> 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:

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

```text theme={null}
Public key: pk_<64 hexadecimal characters>
Secret key: sk_<64 hexadecimal characters>
```

Store them as environment variables:

```bash theme={null}
export EVB_PUBLIC_KEY="pk_your_public_key"
export EVB_SECRET_KEY="sk_your_secret_key"
```

> [!TIP]
>
> 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:

```bash theme={null}
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.

```bash theme={null}
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](https://docs.everabyte.com/api-reference/buckets/overview.md).

## 4. Verify authentication

List the folders in that bucket:

```bash theme={null}
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:

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

```bash theme={null}
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](https://docs.everabyte.com/api-reference/pagination.md).

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

```bash theme={null}
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:

```bash theme={null}
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:

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

> [!WARNING]
>
> 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

```bash theme={null}
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:

```bash theme={null}
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](https://docs.everabyte.com/storage/manage-file-lifecycle.md).

## 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](https://docs.everabyte.com/authentication/api-keys.md) before production.
* Read [Scopes and permissions](https://docs.everabyte.com/authentication/scopes-and-permissions.md) to apply least privilege.
* Read [Upload files](https://docs.everabyte.com/storage/upload-files.md) for multipart limits and safe processing.


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