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

# Square Cloud API: Basis-URL und erste Anfrage

> Einstieg in die Square Cloud REST API: Basis-URL v2, Authorization-Header, eine erste curl-Anfrage, Antwortformat, IDs, Scopes und Fehlerbehandlung.

Die Square Cloud API ist eine REST API über HTTPS. Sie deckt ab, was du im Dashboard erledigst: Anwendungen deployen und steuern, ihre Logs und Metriken lesen, Dateien, Umgebungsvariablen, Snapshots, Datenbanken und Workspaces verwalten. Sie sendet und empfängt JSON, mit zwei Ausnahmen: [Upload](/de/api-reference/endpoint/apps/upload) und [Commit](/de/api-reference/endpoint/apps/commit) nehmen ein Zip als `multipart/form-data` entgegen, und [Echtzeit](/de/api-reference/endpoint/apps/realtime) streamt Server-Sent Events.

## Basis-URL

Jeder Endpoint dieser Referenz ist relativ zu:

```bash theme={"system"}
https://api.squarecloud.app/v2
```

[Blob Storage](/de/blob-reference/quickstart) ist eine eigene API mit eigener Basis-URL, `https://blob.squarecloud.app/v1`, und nimmt denselben API-Schlüssel an.

## Authentifizierung

Erstelle einen API-Schlüssel in deinen [Sicherheitseinstellungen des Kontos](https://squarecloud.app/de/account/security) und sende ihn im Header `Authorization` jeder Anfrage. Das Präfix `Bearer ` ist optional.

```bash theme={"system"}
Authorization: <api_key>
```

Der Schlüssel wird nur einmal angezeigt, beim Erstellen. Bewahre ihn auf deinem Server in einer Umgebungsvariable auf, niemals in clientseitigem Code oder in einem Repository. Jeder Schlüssel hat Scopes, die begrenzen, was er darf: Den Scope jedes Endpoints findest du unter [Authentifizierung](/de/api-reference/authentication).

## Deine erste Anfrage

[Kontoinformationen](/de/api-reference/endpoint/users/me) liefert dein Profil, deinen Plan und jede Anwendung und Datenbank, die dir gehört. Dafür brauchst du einen Schlüssel mit dem Scope `account:read`.

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"

curl https://api.squarecloud.app/v2/users/me \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "user": {
      "id": "1234567890",
      "name": "John Doe",
      "email": "john@example.com",
      "locale": "en-US",
      "plan": {
        "name": "standard-4",
        "memory": { "limit": 4096, "available": 3584, "used": 512 },
        "duration": 1780615237662
      },
      "created_at": "2024-05-01T12:00:00.000Z"
    },
    "applications": [
      {
        "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
        "name": "my-app",
        "ram": 512,
        "lang": "javascript",
        "domain": "my-app.squareweb.app",
        "custom": null,
        "cluster": "example-cluster",
        "created_at": "2024-05-01T12:00:00.000Z"
      }
    ],
    "databases": []
  }
}
```

Bekommst du `401 ACCESS_DENIED`, fehlt der Schlüssel oder wird nicht erkannt. Bekommst du `403 MISSING_SCOPE`, funktioniert der Schlüssel, aber ihm fehlt `account:read`.

## Antwortformat

Ein erfolgreicher Aufruf antwortet mit `2xx` und `"status": "success"` und, wenn es etwas zurückzugeben gibt, mit den Daten in `response`:

```json theme={"system"}
{ "status": "success", "response": { } }
```

Aktionen wie Starten oder Stoppen antworten nur mit `{ "status": "success" }`. Ein fehlgeschlagener Aufruf antwortet mit `4xx` oder `5xx`, `"status": "error"` und einem `code`, nach dem du verzweigen kannst:

```json theme={"system"}
{ "status": "error", "code": "APP_NOT_FOUND" }
```

Feldnamen in Antworten verwenden `snake_case`. Jeder Code steht mit der passenden Lösung unter [Fehler](/de/api-reference/errors).

## IDs

* **Anwendungen und Datenbanken** haben eine 32-stellige hexadezimale ID, etwa `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`. Du findest sie über [Kontoinformationen](/de/api-reference/endpoint/users/me) oder in der Adresse der Ressource im Dashboard.
* **Eine über einen Workspace mit dir geteilte Anwendung** wird im Pfad als `<appId>-<workspaceId>` angesprochen, zum Beispiel `/v2/apps/<appId>-<workspaceId>/status`.
* **Workspaces** haben eine 32-stellige hexadezimale ID. Ältere Workspaces behalten eine 40-stellige.

## Limits

Jedes Konto hat ein Budget an Anfragen pro 60 Sekunden, das sein Plan festlegt, und manche Endpoints haben ein eigenes Limit, das auf ihrer Seite steht. Die Werte findest du unter [Limits und Einschränkungen](/de/api-reference/limitations-and-restrictions), wie `429` funktioniert, unter [Fehler](/de/api-reference/errors#rate-limits).

## OpenAPI-Spezifikation

Die gesamte API ist in einem [OpenAPI-Dokument](/de/api-reference/openapi) unter `https://api.squarecloud.app/v2/openapi.json` beschrieben. Importiere es in Postman oder Insomnia oder generiere daraus einen Client.

<Tip>
  Lieber ein typisierter Client? Die [Square Cloud SDKs](/de/sdks/introduction) für [JavaScript](/de/sdks/js/client), [Python](/de/sdks/py/client) und [Go](/de/sdks/go/client) kapseln jeden Endpoint dieser Referenz, und die [CLI](/de/cli-reference/quickstart) erledigt dieselben Aufgaben im Terminal.
</Tip>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Authentifizierung und Scopes" icon="lock" href="/de/api-reference/authentication">
    Wähle die Scopes, die jede Integration braucht.
  </Card>

  <Card title="Fehlercodes" icon="triangle-exclamation" href="/de/api-reference/errors">
    Jeder Code, den die API liefert, und wie du damit umgehst.
  </Card>

  <Card title="Eine Anwendung hochladen" icon="upload" href="/de/api-reference/endpoint/apps/upload">
    Ein Zip mit einer einzigen Anfrage deployen.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/de/api-reference/limitations-and-restrictions">
    Anfragebudgets pro Plan.
  </Card>
</CardGroup>