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

# Artifacts

> Un formato más: una página web que guarda datos (una encuesta, una lista de equipo, una calculadora).

Un **artifact** es un documento con `format: "artifact"`: en vez de un Word o un PDF, Doconda entrega una página web que
guarda datos. Lo que guarda se mantiene entre visitas.

Se crea, se lista, se sigue y se cobra como cualquier documento. Es privado de tu proyecto: tú decides a quién le
das el enlace (por ejemplo, dentro de tu producto, en un `iframe`).

## Crear uno

Con una frase, y Doconda escribe la página:

```bash theme={null}
curl https://api.eu.doconda.com/v1/documents \
  -H "Authorization: Bearer $DOCONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "artifact", "prompt": "Una encuesta para elegir el menú del viernes, con los resultados en directo" }'
```

O con tu contenido en Markdown, y Doconda lo convierte en la página (respetando tu texto):

```json theme={null}
{ "format": "artifact", "content": { "markdown": "# Menú del viernes\n\nVota entre:\n- Paella\n- Pizza\n- Sushi" }, "style": "colores cálidos, botones grandes" }
```

Cuesta como cualquier documento creado, según su [nivel de calidad](/guides/create#niveles-de-calidad).

Cómo se hace: primero un plan de diseño corto (para qué sirve, secciones, colores y fuentes, interacción) que comprueba
lo que la página puede hacer: guardar en `doconda.db` y usar Tailwind, Chart.js, d3 o dayjs, nada más (sin APIs
externas, correo, pagos ni inicio de sesión; si lo pides, propone cómo resolverlo dentro de la página). Luego escribe un
único HTML con todo dentro (también las imágenes), lo mira en ordenador y en móvil y corrige lo que se ve mal: una vez
en `fast` y `standard`, dos en `best`. El evento `artifact.planned` trae el plan.

Funcionan los tres [modos](/guides/modes): directo, `stream` y `background`. El [estilo](/guides/style), en tus palabras,
describe el aspecto de la página. Un artifact no lleva `sources`.

## Dónde guarda sus datos

Eliges uno de dos modos con `artifact.storage`:

| | `shared` (por defecto) | `local` |
| - | - | - |
| Quién ve los datos | Todos los que abren el enlace ven lo mismo | Cada visitante ve solo los suyos |
| Dónde se guardan | En Doconda | En el navegador de cada persona (no salen de él) |
| Para | Encuestas, listas de equipo, inscripciones, paneles | Calculadoras, borradores, listas personales |
| Tu programa puede leerlos | Sí (`GET /documents/{id}/data`) | No: Doconda nunca los recibe |

```json theme={null}
{ "format": "artifact", "prompt": "Una calculadora de hipoteca que recuerde mis simulaciones", "artifact": { "storage": "local" } }
```

La página es la misma en los dos modos: usa `doconda.db` y Doconda decide dónde guardar.

## El enlace

Cuando está listo, `outputs` trae un `html` cuyo `url` es la página. Ese enlace caduca en 1 hora; pide otro con la
duración que necesites (hasta 7 días):

```bash theme={null}
curl "https://api.eu.doconda.com/v1/documents/doc_…/outputs?expires_in=86400" \
  -H "Authorization: Bearer $DOCONDA_API_KEY"
```

```html theme={null}
<iframe src="ARTIFACT_URL" sandbox="allow-scripts allow-same-origin allow-forms" style="width:100%;height:600px;border:0"></iframe>
```

Cada artifact se sirve en su propio subdominio, aislado de tu web, de Doconda y de los demás artifacts
(`allow-same-origin` se refiere a ese subdominio, que es el suyo).

<Warning>Quien tenga el enlace puede ver la página (y, en `shared`, guardar datos en ella) hasta que caduque. Dalo solo a quien deba usarla.</Warning>

## Guardar datos desde la página

Doconda añade `window.doconda.db` a la página. Guarda JSON por **colección** y **clave**:

```js theme={null}
await doconda.db.set("votes", crypto.randomUUID(), { option: "A" }) // crea o sustituye
await doconda.db.get("votes", "abc")        // → los datos, o null
await doconda.db.list("votes")              // → [{ key, data, updated_at }], lo más reciente primero
await doconda.db.delete("votes", "abc")

// Al momento y cada vez que alguien cambie algo (también otras personas):
const stop = doconda.db.subscribe("votes", (votes) => render(votes))
```

* Nombres de colección y clave: letras, números, `_`, `-` o `.` (hasta 64).
* Cada registro, hasta 16 KB de JSON; cada artifact, hasta 5.000 registros.
* Por artifact y minuto: hasta 1.200 lecturas y 120 escrituras. Por encima, `429 rate_limited`.
* La página se abre aislada: no tiene cookies ni `localStorage`, y no puede leer nada de tu web ni de Doconda.
  Para guardar, usa `doconda.db`.

## Leer los datos desde tu programa

```bash theme={null}
curl https://api.eu.doconda.com/v1/documents/doc_…/data \
  -H "Authorization: Bearer $DOCONDA_API_KEY"
# { "data": [{ "collection": "votes", "records": 42 }] }

curl https://api.eu.doconda.com/v1/documents/doc_…/data/votes \
  -H "Authorization: Bearer $DOCONDA_API_KEY"
```

## Proyectos que no guardan contenido

Si el proyecto tiene el guardado desactivado (o la petición lleva `store: false`), un artifact solo puede ser
`local`, y Doconda no lo aloja: se entrega como un fichero **`artifact.html`** para que lo subas a tu web (a los 15
minutos lo borramos). Sus datos se quedan en el navegador de cada visitante.

## Región

Un artifact vive en la región de su proyecto, igual que los demás documentos: su página y sus datos no salen de ella.


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