---
title: API REST
description: Referencia de los endpoints REST de Moodinary.
---

Base: `https://api.moodinary.com/v1` (alias: `/api/v1`). Especificación: [`/openapi.json`](/openapi.json) · [referencia completa](/desarrollador/referencia/)

:::note\[Requiere plan Horizon]
La API REST es una capacidad del plan **Horizon**. Se gestiona desde
el panel, en **Integraciones → API de lectura**.
:::

## Autenticación

Mandá tu API key como Bearer token. Todos los endpoints devuelven JSON con
los datos de **tu** organización. Además de leer (`GET`), podés crear equipos
y acciones (`POST`) y editar acciones (`PATCH`).

:::caution\[Todo POST lleva Idempotency-Key]
Cada `POST` exige un header `Idempotency-Key` (8 a 128 caracteres). Generá un
UUID por operación, guardalo antes de enviar y reusalo si reintentás la misma
operación con el mismo body. Ver [SDK](/desarrollador/sdk/#crear-y-modificar).
:::

```bash
curl "https://api.moodinary.com/v1/pulses" \
  -H "Authorization: Bearer mpk_live_..."
```

Los errores tienen la forma `{ "error": { "code", "message" } }`. Hay rate
limit por key: si recibís un `429`, el header `Retry-After` te dice cuántos
segundos esperar.

| Código | Cuándo pasa |
| --- | --- |
| `401` | Falta el header `Authorization` o la key es inválida. |
| `403` | La key es válida pero tu plan no incluye la API REST. |
| `404` | Organización no encontrada. |
| `429` | Rate limit por key. Esperá los segundos de `Retry-After`. |

:::tip\[¿No tenés key?]
Se crean desde el panel, en **Integraciones → API de lectura**. La clave se
muestra una sola vez: copiala y guardala en un lugar seguro. [Cómo crear una
key](/desarrollador/api-keys/)
:::

## `GET /v1/org`

Metadata de tu organización.

```json
{
  "id": "org_123",
  "name": "Organización Norte",
  "memberCount": 42,
  "createdAt": "2025-01-14T12:00:00.000Z"
}
```

## `GET /v1/pulses`

Lista paginada de pulsos, del más nuevo al más viejo.

**Parámetros:**

* `from`, `to` — rango en formato ISO. Por defecto: últimos 30 días.
* `subteamId` — filtra por equipo.
* `limit` — 1 a 200. Por defecto: 50.
* `cursor` — `createdAt|id` del último item que viste. Si la respuesta trae
  `nextCursor`, hay más páginas: repetí el llamado con ese cursor.

```json
{
  "items": [
    {
      "id": "pls_abc",
      "level": 4,
      "reason": "TRABAJO",
      "moderationStatus": "CLEAN",
      "subteamId": "sub_1",
      "subteamName": "Ventas",
      "createdAt": "2026-08-18T09:12:00.000Z"
    }
  ],
  "nextCursor": "2026-08-18T09:12:00.000Z|pls_abc"
}
```

## `GET /v1/stats/daily`

Agregados por día: cantidad de pulsos y promedio de nivel. Ideal para
graficar la evolución en tu BI.

**Parámetros:**

* `from`, `to` — rango en formato ISO. Por defecto: últimos 90 días
  (máximo un año hacia atrás).

```json
{
  "from": "2026-05-21T00:00:00.000Z",
  "to": "2026-08-19T00:00:00.000Z",
  "days": [{ "date": "2026-08-18", "count": 12, "avg": 3.75 }]
}
```

## `GET /v1/alerts`

Las alertas inteligentes más recientes de tu organización.

**Parámetros:**

* `limit` — 1 a 50. Por defecto: 10.

```json
{
  "items": [
    {
      "id": "alt_1",
      "type": "anomaly_drop",
      "message": "Caída sostenida en Ventas",
      "weekISO": "2026-W33",
      "subteamName": "Ventas",
      "readAt": null,
      "createdAt": "2026-08-17T08:00:00.000Z"
    }
  ]
}
```