Todos os endpoints, uma única URL base.
Nenhum SDK necessário - qualquer cliente HTTP funciona. URL base https://api.wontopos.com, autenticação via o cabeçalho X-API-Key, JSON na entrada e na saída. As operações de memória são POST; gerenciar stores usa POST / GET / DELETE em /collection. Um store precisa existir primeiro (veja Stores), ou as operações dentro do store retornam 404.
Cabeçalhos
| Cabeçalho | O que faz |
|---|---|
| X-API-Key | Obrigatório em toda chamada. Sua chave, emitida no console. |
| X-WOS-Model | Opcional. Qual motor responde. Omita e o padrão da conta é usado. GET /api/v1/models lista os modelos que a sua chave pode selecionar; um endpoint que um motor mais antigo não consegue atender responde 501 e informa esse modelo. |
| Idempotency-Key | Opcional, nas escritas. A mesma chave com o mesmo corpo repete a primeira resposta em vez de armazenar de novo - veja a nota abaixo. |
Endpoint
| Endpoint | Finalidade | Campos do corpo |
|---|---|---|
| POST /api/v1/memory/collection | criar um store | user_id |
| GET /api/v1/memory/collections | listar seus stores | (nenhum) |
| DELETE /api/v1/memory/collection | excluir um store + suas memórias | user_id |
| /api/v1/memory/store | armazenar uma memória | user_id · content · metadata? (event_date · speaker) · image? |
| /api/v1/memory/store-turn | armazenar um turno de conversa | user_id · user_msg · assistant_msg |
| POST /api/v1/memory/speakers | registrar um falante (explícito, até 50) | user_id · speaker |
| GET /api/v1/memory/speakers | listar falantes registrados + contagens | user_id |
| DELETE /api/v1/memory/speakers | remover um falante (memórias ficam) | user_id · speaker |
| /api/v1/memory/by-speaker | o que uma pessoa disse, do mais recente ("me" = o agente) | user_id · speaker · limit? · before? · skip_ids? |
| POST /api/v1/memory/image | a imagem que guardamos de uma memória com imagem - não o seu original | user_id · memory_id |
| DELETE /api/v1/memory/image | remover a imagem e manter a legenda | user_id · memory_id · preview? |
| /api/v1/memory/images | as imagens de um store, do mais recente (+ o total) | user_id · limit? · before? · skip_ids? |
| /api/v1/memory/lineage | a cadeia de edições de uma memória, do mais antigo | user_id · memory_id |
| GET /api/v1/won/usage | O que esta chave gastou e o que resta — para um modelo decidir se continua. Grátis. | days? |
| GET /api/v1/memory/usage | O que esta chave gastou e o que resta — para um modelo decidir se continua. Grátis. | days? |
| /api/v1/won/revisions | quanto de um store foi reescrito. Grátis | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/revisions | a mesma chamada sob o plano memory. Grátis | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/bulk-store | backfill de um bloco de texto | user_id · content · category? · timestamp? |
| /api/v1/memory/search | busca semântica | user_id · query · max_results? · speaker? · cache_control? · filters? · verify? · max_images? |
| /api/v1/memory/recall | curto + longo + contexto | user_id · query · limit? · context_limit? |
| /api/v1/memory/get | uma memória por id | user_id · memory_id |
| /api/v1/memory/list | percorrer um repositório por páginas | user_id · limit? · cursor? |
| /api/v1/memory/history | turnos recentes | user_id |
| /api/v1/memory/stats | contagens de memórias | user_id |
| /api/v1/memory/supersede | substituir um fato que mudou | user_id · old_memory_id · new_content |
| /api/v1/memory/forget | excluir uma (ou todas) | user_id · memory_id? (omitir = excluir tudo) |
| GET /api/v1/engram | engramas que este modelo pode executar | (nenhum) |
| POST /api/v1/engram/run | executar um engrama | name · user_id · query · form? · tz? |
| GET /api/v1/models | modelos disponíveis | (nenhum) |
As escritas aceitam o cabeçalho
Idempotency-Key. A mesma chave com o mesmo corpo repete a primeira resposta em vez de armazenar de novo (10 minutos); a mesma chave com corpo diferente responde 422. Apenas 2xx são cacheados, portanto uma chamada que falhou pode ser repetida na hora.# 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?"}'
Resposta real - store
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}