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

# API de Scripts

> Dirección, autenticación, alcances, límites y webhooks de la API de Scripts.

La **API de Scripts** te da acceso a tus scripts por HTTP: código, ramas, commits, funciones del backend, colecciones, webhooks, IA y Studio (versiones, usuarios, configuración).

## Dirección

```text theme={null}
https://ucsyxzpdbnuyehizezvb.supabase.co/functions/v1/doglytdc-scripts-api
```

El índice completo, legible por máquina, está en [`/scripts.json`](https://ucsyxzpdbnuyehizezvb.supabase.co/functions/v1/doglytdc-scripts-api/scripts.json) (sin autenticación).

## Autenticación

Envía `Authorization: Bearer <token>` en cada solicitud.

| Credencial | Prefijo | Cómo obtenerla |
| - | - | - |
| `script_token` | `dts_…` | **Painel Dev** (Panel de desarrollo) › API › **Gerar token** (Generar token). Solo sirve para ese script, con todos los alcances. |
| `oauth2` | — | Hub OAuth2 con PKCE: [https://doglytdc.dev/oauth2/authorize](https://doglytdc.dev/oauth2/authorize) (mismo flujo de /v1/hub). Solicita los alcances que se indican abajo. |
| `session` | — | Sesión de DoglyTdc (usada por el panel). Las rutas marcadas como session solo aceptan esta. |

> [!WARNING]
>
> Nunca coloques el token dentro del script que se distribuye a los usuarios. Da acceso al código y al backend del script.

## Alcances

| Alcance | Qué permite |
| - | - |
| `scripts.read` | Ver tus scripts, código, commits, funciones y colecciones |
| `scripts.write` | Crear y editar scripts, hacer commits y administrar webhooks |
| `functions.deploy` | Publicar el backend (funciones y colecciones) de los scripts |
| `ai` | Usar la IA DoglyTdc con los créditos del propietario del script |
| `scripts.publish` | Publicar versiones protegidas y volver a versiones anteriores |
| `users.manage` | Ver quién usa tus scripts y bloquear, desactivar o reactivar usuarios |

Si falta el alcance, la respuesta es `403 MISSING_SCOPE`.

## Formato

* Solicitudes y respuestas en JSON (`Content-Type: application/json`).
* Errores: `{ "code": "…", "message": "…", "errors": { … } }`. `errors` aparece cuando un campo es incorrecto. Consulta la [lista de errores](https://docs.doglytdc.dev/es/scripts/errors.md).
* Fechas en ISO 8601 (UTC).
* Las cuentas aparecen siempre como `@username`.

## Límites

| Qué | Límite |
| - | - |
| Llamadas autenticadas | 300 por minuto (por script con token de script, por cuenta en los demás casos) |
| Rutas públicas (sin iniciar sesión) | 120 por minuto por dirección |
| Commits | 30 por minuto por persona y script |
| Llamar a una función | 120 por minuto por persona y script |
| IA | 20 mensajes por minuto por persona y script |
| MCP | 120 mensajes por minuto por cuenta |

Al superarlo, la respuesta es `429 RATE_LIMITED` con `Retry-After: 60`.

## Webhooks

| Elemento | Valor |
| - | - |
| Eventos | `repo.commit`, `functions.deploy`, `access.granted`, `ping` |
| Encabezados | `X-DoglyTdc-Signature`, `X-DoglyTdc-Timestamp`, `X-DoglyTdc-Event`, `X-DoglyTdc-Delivery` |
| Cuerpo | `{ id, event, script_id, created_at, data }` |
| Firma | `sha256=hex(HMAC_SHA256(chave, timestamp + "." + corpo_bruto))`; rechaza las marcas de tiempo de más de 5 minutos |
| Intentos | 3 (de inmediato, después de 1 s y de 3 s); el webhook se desactiva después de 10 fallos consecutivos |

Verificar la firma (Node.js):

```js theme={null}
import crypto from "node:crypto";

function assinaturaValida(req, corpoBruto, chave) {
  const ts = req.headers["x-doglytdc-timestamp"];
  const sig = req.headers["x-doglytdc-signature"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const esperado = "sha256=" + crypto.createHmac("sha256", chave).update(ts + "." + corpoBruto).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(esperado));
}
```

## Ejemplos

### Leer un archivo

```bash theme={null}
curl -H "Authorization: Bearer dts_…" https://ucsyxzpdbnuyehizezvb.supabase.co/functions/v1/doglytdc-scripts-api/scripts/{script_id}/repo/files/src/script.js?raw=1
```

### Commit con protección contra condiciones de carrera

```bash theme={null}
curl -X POST -H "Authorization: Bearer dts_…" -H "Content-Type: application/json" https://ucsyxzpdbnuyehizezvb.supabase.co/functions/v1/doglytdc-scripts-api/scripts/{script_id}/repo/commits -d '{"expected_head":"<head_sha de GET /repo/branches>","message":"Atualiza script","changes":[{"path":"src/script.js","content":"console.log(1)"}]}'
```

### IA

```bash theme={null}
curl -X POST -H "Authorization: Bearer dts_…" -H "Content-Type: application/json" https://ucsyxzpdbnuyehizezvb.supabase.co/functions/v1/doglytdc-scripts-api/ai/chat -d '{"messages":[{"role":"user","content":"Oi"}]}'
```

## Rutas

> [card] [Scripts](https://docs.doglytdc.dev/es/scripts/api-reference/scripts.md)
>
> 6 ruta(s)

> [card] [Token del script](https://docs.doglytdc.dev/es/scripts/api-reference/token.md)
>
> 3 ruta(s)

> [card] [Repositorio](https://docs.doglytdc.dev/es/scripts/api-reference/repository.md)
>
> 7 ruta(s)

> [card] [Funciones y publicación del backend](https://docs.doglytdc.dev/es/scripts/api-reference/backend.md)
>
> 3 ruta(s)

> [card] [Colecciones y documentos](https://docs.doglytdc.dev/es/scripts/api-reference/collections.md)
>
> 6 ruta(s)

> [card] [Webhooks](https://docs.doglytdc.dev/es/scripts/api-reference/webhooks.md)
>
> 6 ruta(s)

> [card] [IA y registros](https://docs.doglytdc.dev/es/scripts/api-reference/ai-and-logs.md)
>
> 2 ruta(s)

> [card] [Apps autorizadas](https://docs.doglytdc.dev/es/scripts/api-reference/authorizations.md)
>
> 2 ruta(s)

> [card] [Studio](https://docs.doglytdc.dev/es/scripts/api-reference/studio.md)
>
> Versiones, usuarios, configuración


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