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

# API REST

> Conecta Wudlet con productos como Custumu, Power BI o tu propio backend. Autentica con una clave de proyecto y consulta visibilidad, prompts, competidores, citas y brechas de contenido.

La API pública de Wudlet entrega los mismos datos que ves en el panel: puntuación de visibilidad, prompts rastreados, menciones de competidores, citas y huecos de contenido. Está pensada para clientes enterprise (por ejemplo Custumu) que necesitan leer esa información por REST.

<Note>
  Esta sección documenta únicamente la API de lectura `/v1`. Las rutas internas del panel (`/api/ai-visibility`, autenticación de sesión, etc.) no forman parte de este contrato.
</Note>

## URL base

La API pública vive solo en producción:

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

`https://api.wudlet.com/api/v1` es el mismo contrato. No uses `localhost` ni entornos de desarrollo: las integraciones (Custumu, Power BI, tu backend) deben apuntar siempre a `https://api.wudlet.com`.

## Autenticación

Crea una clave en **Configuración → Developer Settings** (o **Claves de API** del proyecto). Las claves públicas empiezan por `pk_live_` y las secretas por `sk_live_`. Cualquiera de las dos sirve para esta API si está activa y no ha caducado.

Envía la clave en cada petición:

<CodeGroup>
  ```bash Authorization theme={null}
  curl https://api.wudlet.com/v1/brands \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```bash X-Api-Key theme={null}
  curl https://api.wudlet.com/v1/brands \
    -H "X-Api-Key: sk_live_..."
  ```
</CodeGroup>

<ParamField header="Authorization" type="string" required>
  `Bearer` seguido de la clave. Ejemplo: `Bearer sk_live_abc123`.
</ParamField>

<ParamField header="X-Api-Key" type="string">
  Alternativa a `Authorization`. Mismo valor de la clave, sin el prefijo `Bearer`.
</ParamField>

<ParamField header="X-Timezone" type="string">
  Zona horaria IANA para filtrar fechas (`America/Guatemala`, `UTC`). Si se omite, se usa `UTC`.
</ParamField>

Si falta la clave, la API responde `401`. Si está revocada, caducada o es inválida, también `401`.

## Alcance de la clave

Cada clave pertenece a **un proyecto**. Solo verás las marcas y los resultados de visibilidad de ese proyecto. No hace falta enviar `org_id` ni `project_id` en la URL.

## Parámetros comunes

Muchos endpoints aceptan los mismos filtros de consulta:

<ParamField query="brand_id" type="uuid">
  Identificador de la marca. También se acepta `brand` con el dominio o el nombre. Si se omite, Wudlet usa la marca principal del proyecto.
</ParamField>

<ParamField query="start_date" type="date">
  Inicio del rango (`YYYY-MM-DD`), interpretado en la zona de `X-Timezone`.
</ParamField>

<ParamField query="end_date" type="date">
  Fin del rango (`YYYY-MM-DD`).
</ParamField>

<ParamField query="model" type="string">
  Uno o varios motores separados por coma. Ejemplo: `chatgpt,claude,gemini`.
</ParamField>

<ParamField query="page" type="integer">
  Página (empieza en `1`).
</ParamField>

<ParamField query="limit" type="integer">
  Tamaño de página. El máximo depende del endpoint (50–100).
</ParamField>

## Catálogo de endpoints

<CardGroup cols={2}>
  <Card title="Marcas" icon="building" href="/api/marcas">
    Lista las marcas del proyecto asociado a la clave.
  </Card>

  <Card title="Visibilidad" icon="chart-line" href="/api/visibilidad">
    Puntuación global y desglose por modelo de IA.
  </Card>

  <Card title="Instantánea" icon="camera" href="/api/instantanea">
    Score, prompts sin mención, competidores y brechas en una sola respuesta.
  </Card>

  <Card title="Prompts" icon="message" href="/api/prompts">
    Biblioteca de consultas y recuento de menciones.
  </Card>

  <Card title="Competidores" icon="users" href="/api/competidores">
    Marcas que la IA nombra en lugar de la tuya.
  </Card>

  <Card title="Citas" icon="link" href="/api/citas">
    Dominios que los modelos citan en sus respuestas.
  </Card>

  <Card title="Brechas de contenido" icon="file-pen" href="/api/brechas-de-contenido">
    Prompts que pierdes y ángulos de contenido para cerrarlos.
  </Card>
</CardGroup>

## Errores

| Código | Significado                                     |
| ------ | ----------------------------------------------- |
| `401`  | Falta la clave, o no es válida / está revocada. |
| `500`  | Error interno al leer visibilidad o marcas.     |

El cuerpo de error es JSON: `{ "error": "mensaje" }`.

## Custumu y otros clientes

Custumu consume esta API como cliente enterprise. En el backend de Custumu configura:

```env theme={null}
WUDLET_API_KEY=sk_live_...
WUDLET_BRAND_ID=
WUDLET_TIMEZONE=America/Guatemala
```

Custumu llama siempre a `https://api.wudlet.com`. Solo necesitas la clave de un proyecto de Wudlet.

Custumu llama sobre todo a `GET /v1/visibility/snapshot` para mostrar si la marca aparece en las respuestas de IA y para redactar contenido a partir de los prompts que faltan.