Todos los endpoints, una URL base.
No se requiere SDK - cualquier cliente HTTP funciona. URL base https://api.wontopos.com, autenticación vía el encabezado X-API-Key, JSON de entrada y salida. Las operaciones de memoria son POST; la administración de stores usa POST / GET / DELETE sobre /collection. El store debe existir primero (ver Stores) o las operaciones dentro del store devuelven 404.
Encabezados
| Encabezado | Qué hace |
|---|---|
| X-API-Key | Obligatorio en cada llamada. Tu clave, emitida en la consola. |
| X-WOS-Model | Opcional. Qué motor responde. Omítelo y se usa el valor por defecto de la cuenta. GET /api/v1/models lista los modelos que tu clave puede seleccionar; un endpoint que un motor anterior no puede atender responde 501 y nombra ese modelo. |
| Idempotency-Key | Opcional, en las escrituras. La misma clave con el mismo cuerpo reproduce la primera respuesta en lugar de volver a almacenar - mira la nota de abajo. |
Endpoint
| Endpoint | Propósito | Campos del cuerpo |
|---|---|---|
| POST /api/v1/memory/collection | crear un store | user_id |
| GET /api/v1/memory/collections | listar tus stores | (ninguno) |
| DELETE /api/v1/memory/collection | eliminar un store + sus memorias | user_id |
| /api/v1/memory/store | almacenar una memoria | user_id · content · metadata? (event_date · speaker) · image? |
| /api/v1/memory/store-turn | almacenar un turno de conversación | user_id · user_msg · assistant_msg |
| POST /api/v1/memory/speakers | registrar un hablante (explícito, hasta 50) | user_id · speaker |
| GET /api/v1/memory/speakers | listar hablantes registrados + conteos | user_id |
| DELETE /api/v1/memory/speakers | dar de baja un hablante (los recuerdos quedan) | user_id · speaker |
| /api/v1/memory/by-speaker | lo que dijo una persona, de lo más reciente («me» = el agente) | user_id · speaker · limit? · before? · skip_ids? |
| POST /api/v1/memory/image | la imagen que guardamos de una memoria con imagen; no su original | user_id · memory_id |
| DELETE /api/v1/memory/image | quitar la imagen y conservar el texto | user_id · memory_id · preview? |
| /api/v1/memory/images | las imágenes de un store, de lo más reciente (+ el total) | user_id · limit? · before? · skip_ids? |
| /api/v1/memory/lineage | la cadena de ediciones de una memoria, de lo más antiguo | user_id · memory_id |
| GET /api/v1/won/usage | Lo que ha gastado esta clave y lo que queda — para que un modelo decida si continuar. Gratis. | days? |
| GET /api/v1/memory/usage | Lo que ha gastado esta clave y lo que queda — para que un modelo decida si continuar. Gratis. | days? |
| /api/v1/won/revisions | cuánto de un store se ha reescrito. Gratis | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/revisions | la misma llamada bajo el plano memory. Gratis | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/bulk-store | rellenar un bloque de texto | user_id · content · category? · timestamp? |
| /api/v1/memory/search | búsqueda semántica | user_id · query · max_results? · speaker? · cache_control? · filters? · verify? · max_images? |
| /api/v1/memory/recall | corto + largo + contexto | user_id · query · limit? · context_limit? |
| /api/v1/memory/get | una memoria por id | user_id · memory_id |
| /api/v1/memory/list | recorrer un almacén por páginas | user_id · limit? · cursor? |
| /api/v1/memory/history | turnos recientes | user_id |
| /api/v1/memory/stats | conteos de memoria | user_id |
| /api/v1/memory/supersede | reemplazar un hecho que cambió | user_id · old_memory_id · new_content |
| /api/v1/memory/forget | eliminar una (o todas) | user_id · memory_id? (omitir = eliminar todo) |
| GET /api/v1/engram | engramas que este modelo puede ejecutar | (ninguno) |
| POST /api/v1/engram/run | ejecutar un engrama | name · user_id · query · form? · tz? |
| GET /api/v1/models | modelos disponibles | (ninguno) |
Las escrituras aceptan una cabecera
Idempotency-Key. La misma clave con el mismo cuerpo reproduce la primera respuesta en lugar de volver a almacenar (10 minutos); la misma clave con un cuerpo distinto responde 422. Solo se cachean los 2xx, así que una llamada fallida se puede reintentar de inmediato.# create the store once (stores are explicit) curl -X POST https://api.wontopos.com/api/v1/memory/collection \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice"}' # store a memory curl -X POST https://api.wontopos.com/api/v1/memory/store \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","content":"she prefers tea over coffee"}' # recall - one call, ready for your prompt curl -X POST https://api.wontopos.com/api/v1/memory/recall \ -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \ -d '{"user_id":"alice","query":"what does alice drink?"}'
Respuesta real - store
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}