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

# API de Square Cloud: URL base y primera solicitud

> Empieza con la API REST de Square Cloud: URL base v2, encabezado Authorization, una primera solicitud con curl, formato de respuesta, IDs, scopes y errores.

La API de Square Cloud es una API REST sobre HTTPS. Cubre lo que haces en el panel: hacer deploy y controlar aplicaciones, leer sus logs y métricas, y gestionar archivos, variables de entorno, snapshots, bases de datos y workspaces. Envía y recibe JSON, con dos excepciones: [upload](/es/api-reference/endpoint/apps/upload) y [commit](/es/api-reference/endpoint/apps/commit) reciben un zip como `multipart/form-data`, y [realtime](/es/api-reference/endpoint/apps/realtime) transmite Server-Sent Events.

## URL base

Todos los endpoints de esta referencia son relativos a:

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

[Blob Storage](/es/blob-reference/quickstart) es una API aparte con su propia URL base, `https://blob.squarecloud.app/v1`, y acepta la misma clave de API.

## Autenticación

Crea una clave de API en la [configuración de seguridad de tu cuenta](https://squarecloud.app/es/account/security) y envíala en el encabezado `Authorization` de cada solicitud. El prefijo `Bearer ` es opcional.

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

La clave se muestra una sola vez, al crearla. Guárdala en tu servidor, en una variable de entorno, y nunca en código del lado del cliente ni en un repositorio. Cada clave tiene scopes que limitan lo que puede hacer: consulta [Autenticación](/es/api-reference/authentication) para ver el scope de cada endpoint.

## Tu primera solicitud

[Información de la cuenta](/es/api-reference/endpoint/users/me) devuelve tu perfil, tu plan y todas las aplicaciones y bases de datos que te pertenecen. Necesita una clave con el 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": []
  }
}
```

Si recibes `401 ACCESS_DENIED`, la clave falta o no se reconoce. Si recibes `403 MISSING_SCOPE`, la clave funciona pero no tiene `account:read`.

## Formato de respuesta

Una llamada correcta responde `2xx` con `"status": "success"` y, cuando hay algo que devolver, los datos en `response`:

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

Las acciones como iniciar o detener responden solo `{ "status": "success" }`. Una llamada fallida responde `4xx` o `5xx` con `"status": "error"` y un `code` con el que decidir qué hacer:

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

Los nombres de los campos en las respuestas usan `snake_case`. Todos los códigos, con lo que debes hacer en cada caso, están en [Errores](/es/api-reference/errors).

## IDs

* **Las aplicaciones y bases de datos** tienen un id hexadecimal de 32 caracteres, como `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`. Obtenlos en [Información de la cuenta](/es/api-reference/endpoint/users/me) o en la dirección del recurso en el panel.
* **Una aplicación compartida contigo a través de un workspace** se indica como `<appId>-<workspaceId>` en la ruta, por ejemplo `/v2/apps/<appId>-<workspaceId>/status`.
* **Los workspaces** tienen un id hexadecimal de 32 caracteres. Los workspaces más antiguos conservan uno de 40 caracteres.

## Límites

Cada cuenta tiene un presupuesto de solicitudes por cada 60 segundos, definido por su plan, y algunos endpoints tienen su propio límite, indicado en su página. Consulta [Límites y restricciones](/es/api-reference/limitations-and-restrictions) para ver los valores y [Errores](/es/api-reference/errors#límites-de-tasa) para saber cómo funciona el `429`.

## Especificación OpenAPI

Toda la API está descrita en un [documento OpenAPI](/es/api-reference/openapi) en `https://api.squarecloud.app/v2/openapi.json`. Impórtalo en Postman o Insomnia, o genera un cliente a partir de él.

<Tip>
  ¿Prefieres un cliente tipado? Los [SDKs de Square Cloud](/es/sdks/introduction) para [JavaScript](/es/sdks/js/client), [Python](/es/sdks/py/client) y [Go](/es/sdks/go/client) cubren todos los endpoints de esta referencia, y la [CLI](/es/cli-reference/quickstart) cubre las mismas tareas desde una terminal.
</Tip>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Autenticación y scopes" icon="lock" href="/es/api-reference/authentication">
    Elige los scopes que necesita cada integración.
  </Card>

  <Card title="Códigos de error" icon="triangle-exclamation" href="/es/api-reference/errors">
    Todos los códigos que devuelve la API y cómo gestionarlos.
  </Card>

  <Card title="Subir una aplicación" icon="upload" href="/es/api-reference/endpoint/apps/upload">
    Haz deploy de un zip con una sola solicitud.
  </Card>

  <Card title="Límites de tasa" icon="gauge" href="/es/api-reference/limitations-and-restrictions">
    Presupuestos de solicitudes por plan.
  </Card>
</CardGroup>