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

# API para desarrolladores

> La API REST pública para construir sobre wondeya: URL base, autenticación, convenciones y versionado

La API para desarrolladores de wondeya es una superficie REST bajo `/v1`, autenticada con una **clave de API de espacio de trabajo** que creas en la consola. Te permite automatizar todo lo que hace el producto (agentes, proyectos, páginas, conocimiento, recursos, marca, tema, uso) y hablar con un agente directamente: recuperación, y un turno generativo headless. Las páginas de endpoints de esta pestaña se generan a partir del documento OpenAPI de wondeya, así que describen exactamente lo que el servidor acepta. Las páginas generadas de endpoints (el grupo Endpoints) se sirven en inglés.

## URL base

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

El desarrollo local corre en `http://localhost:8080/v1`.

## Autenticación en una línea

Cada solicitud lleva una clave como token bearer:

```bash theme={null}
curl https://api.wondeya.com/v1/me \
  -H "Authorization: Bearer wdy_live_…"
```

Una clave está acotada a **un espacio de trabajo** y a permisos explícitos, y el espacio de trabajo es el de la CLAVE: ninguna solicitud nombra un `tenantId`, así que una clave solo puede alcanzar su propio espacio de trabajo. Crea una clave y mira el flujo completo en la página de [Autenticación](/docs/es/api-reference/authentication).

## El modelo

```
Workspace
├── Agent[]     the brain: knowledge, images, identity, and the chat that answers
└── Project[]   the site: its address (<slug>.wondeya.app), its brand, its pages
    └── Page[]  a path inside the project: an agent page, or a document page
```

Un **agente** se configura una vez y se reutiliza; un **proyecto** es un sitio con una dirección pública; una **página** vive dentro de un proyecto y es o bien una página `agent` (la opción por defecto, que nombra al agente que responde en ella) o bien una página `document` (que renderiza un cuerpo en markdown, sin agente). Varias páginas pueden compartir un agente, y por eso los agentes son de nivel de espacio de trabajo.

## Convenciones

**La creación responde `201`, las transiciones de estado responden `200`.** Publicar y despublicar una página son endpoints propios (`/publish`, `/unpublish`), nunca un campo en el patch de configuración.

**Las actualizaciones son parciales y se fusionan.** Un `PATCH` lleva solo lo que cambió. Un patch de tema lleva solo los tokens que cambiaron, pero un token fuera del conjunto cerrado es un `400`, nunca un campo ignorado.

**La ingesta es asíncrona.** `POST /v1/knowledge/text` y `/urls` responden `202` con la fuente `pending`; consulta periódicamente `GET /v1/knowledge/sources` hasta que esté `ready` o `failed`. El código que asuma que la subida es síncrona leerá `chunkCount: 0` y parecerá roto.

**Las listas se paginan por cursor.** Toda lista responde `{ data, hasMore, nextCursor }`; sigue `nextCursor` como `?after=`. Mira [Paginación](/docs/es/api-reference/pagination).

**Los reintentos son seguros cuando lo pides.** Envía un `Idempotency-Key` en una creación y un reintento repite la primera respuesta en lugar de crear un segundo recurso o gastar un segundo crédito de chat. Mira [Idempotencia](/docs/es/api-reference/idempotency).

**Las URLs firmadas expiran.** Las URLs de los recursos están firmadas y son de corta vida (unos 15 minutos). Vuelve a pedir la lista en lugar de cachearlas.

## Límites de tasa

Cada solicitud a `/v1` tiene límite de tasa **por clave**, y cada respuesta anuncia el presupuesto tanto en los encabezados `X-RateLimit-*` como en los encabezados `RateLimit` del IETF. Superar el límite es un `429` con `Retry-After`. Mira [Límites de tasa](/docs/es/api-reference/rate-limits).

## Errores

Todo error es un documento de problema [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`) con un `code` estable y legible por máquina. [Errores](/docs/es/api-reference/errors) los lista y explica sobre qué ramificar tu código.

## Versionado

La superficie se versiona en la ruta (`/v1`). Dentro de `v1` los cambios son **aditivos** (endpoints y campos nuevos, nunca uno eliminado o renombrado), y un cambio incompatible sale como un nuevo `/v2`. Todo lo que está por retirarse se marca `deprecated` en estas páginas antes de eliminarse. Mira [Versionado](/docs/es/api-reference/versioning).

<Note>
  El [servidor MCP](/docs/es/mcp/introduction) es una superficie distinta para un
  llamador distinto: se autentica con OAuth 2.1 (un inicio de sesión en el
  navegador que tú apruebas), para clientes de IA como Claude. Las claves de API
  de máquina son para ESTA API REST.
</Note>


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