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

# Introduction

> Everything you need to know before making your first request to the CamposCloud API.

## Base URL

All endpoints of the API are served over HTTPS under the following base URL:

```
https://api.camposcloud.com/v1
```

## Authentication

All API endpoints are authenticated using your API Key, sent as a Bearer token in the `Authorization` header. See [Authentication](https://docs.camposcloud.com/api-reference/authentication.md) to learn how to get one.

```bash theme={null}
curl https://api.camposcloud.com/v1/users/@me \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"
```

## Requests

* Request bodies are sent as JSON (`Content-Type: application/json`), except for the endpoints that receive a file (`POST /v1/apps/create` and `POST /v1/apps/{appId}/upload`), which use `multipart/form-data`.
* IDs (applications, teams, users) are 24 character hexadecimal strings.
* Some endpoints reject fields they do not know with a `400` error, so only send the fields that are documented.

## Responses

Successful responses are JSON, except for `GET /v1/apps/{appId}/download`, which returns a zip archive.

## Errors

Every error is returned with the matching HTTP status and a JSON body with a single `error` field:

```json theme={null}
{
  "error": "Application not found."
}
```

> [!NOTE]
>
> Error messages are meant for humans and can be in English or in Portuguese depending on the endpoint. Use the HTTP status, not the message, in your code.

| Status | Meaning |
| - | - |
| `400` | The request is invalid: a parameter is missing, has the wrong format or is not allowed. |
| `401` | The API Key is missing or invalid. |
| `403` | You are not allowed to perform the action (not the owner, missing team permission or no active plan). |
| `404` | The resource does not exist, or you do not have access to it. |
| `429` | A [rate limit](https://docs.camposcloud.com/api-reference/api-limits.md) was exceeded. |
| `500` | Unexpected error. Some predictable situations also end here, for example starting an application that is already running or reading a file that does not exist. They are listed in each endpoint. |
| `503` | No node is available to host a new application. |

## Pagination

`GET /v1/apps` is paginated. It returns 10 applications per page by default and accepts the `page` and `limit` query parameters. The response includes a `pagination` object:

```json theme={null}
{
  "applications": [],
  "totalUsedRAM": 768,
  "pagination": {
    "totalItems": 12,
    "totalPages": 2,
    "currentPage": 1,
    "itemsPerPage": 10,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

Keep requesting the next page while `hasNextPage` is `true`.

## Teams and permissions

Applications can belong to a team. The owner of a team can do everything; members can only do what their permissions allow. The permission required by each endpoint is listed in its description.

| Permission | Allows |
| - | - |
| `canCreateApplication` | Create applications in the team. |
| `canDeleteApplication` | Delete applications of the team. |
| `canUpdateApplicationSettings` | Update the settings of applications of the team. |
| `canChangeStatusApplication` | Start, stop and restart applications of the team. |
| `canSeeApplicationFiles` | List, read and download files of applications of the team. |
| `canEditApplicationFiles` | Upload files to applications of the team. |
| `canDeleteApplicationFiles` | Delete files of applications of the team. |
| `canManageApplicationBackup` | Manage backups of applications of the team. |
| `canCreateDatabase` | Create databases in the team. |
| `canDeleteDatabase` | Delete databases of the team. |
| `canUpdateDatabaseSettings` | Update the settings of databases of the team. |
| `canChangeStatusDatabase` | Start, stop and restart databases of the team. |


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