모든 엔드포인트, 하나의 Base URL.
SDK 없이도 됩니다 - 어떤 HTTP 클라이언트든 가능. Base URL https://api.wontopos.com, 인증은 X-API-Key 헤더, 입출력은 JSON. 기억 작업은 POST, 저장소 관리는 /collection에 POST / GET / DELETE. 저장소가 먼저 있어야 하고(Stores 참고), 없으면 404.
헤더
| 헤더 | 하는 일 |
|---|---|
| X-API-Key | 모든 호출에 필수입니다. 콘솔에서 발급한 키입니다. |
| X-WOS-Model | 선택입니다. 어느 엔진이 답할지 고릅니다. 생략하면 계정 기본값을 씁니다. GET /api/v1/models 로 이 키가 고를 수 있는 모델을 볼 수 있고, 이전 엔진이 못 하는 엔드포인트는 501 과 함께 어떤 모델인지 알려줍니다. |
| Idempotency-Key | 쓰기에서 선택입니다. 같은 키에 같은 바디로 보내면 다시 저장하지 않고 첫 응답을 그대로 돌려줍니다 - 아래 주석을 보세요. |
엔드포인트
| 엔드포인트 | 용도 | 바디 필드 |
|---|---|---|
| POST /api/v1/memory/collection | 저장소 생성 | user_id |
| GET /api/v1/memory/collections | 저장소 목록 | (없음) |
| DELETE /api/v1/memory/collection | 저장소 + 기억 삭제 | user_id |
| /api/v1/memory/store | 기억 하나 저장 | user_id · content · metadata? (event_date · speaker) · image? |
| /api/v1/memory/store-turn | 대화 턴 저장 | user_id · user_msg · assistant_msg |
| POST /api/v1/memory/speakers | 화자 등록 (명시적, 50명까지) | user_id · speaker |
| GET /api/v1/memory/speakers | 등록된 화자 목록 + 기억 수 | user_id |
| DELETE /api/v1/memory/speakers | 화자 등록 해제 (기억은 유지) | user_id · speaker |
| /api/v1/memory/by-speaker | 한 사람이 한 말, 최신순 ("me" = 에이전트 자신) | user_id · speaker · limit? · before? · skip_ids? |
| POST /api/v1/memory/image | 이미지 기억에서 저희가 들고 있는 그림 (원본이 아닙니다) | user_id · memory_id |
| DELETE /api/v1/memory/image | 이미지만 지우고 글은 남깁니다 | user_id · memory_id · preview? |
| /api/v1/memory/images | 저장소의 이미지, 최신순 (+ 전체 개수) | user_id · limit? · before? · skip_ids? |
| /api/v1/memory/lineage | 기억 하나의 수정 이력, 오래된 순 | user_id · memory_id |
| GET /api/v1/won/usage | 이 키가 쓴 비용과 남은 잔액 — 모델이 계속할지 판단하는 근거. 무료. | days? |
| GET /api/v1/memory/usage | 이 키가 쓴 비용과 남은 잔액 — 모델이 계속할지 판단하는 근거. 무료. | days? |
| /api/v1/won/revisions | 저장소가 얼마나 고쳐졌는지. 무료 | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/revisions | 같은 호출을 memory 주소에서. 무료 | user_id · include? · limit? · before? · skip_ids? |
| /api/v1/memory/bulk-store | 긴 텍스트 적재 | user_id · content · category? · timestamp? |
| /api/v1/memory/search | 의미 검색 | user_id · query · max_results? · speaker? · cache_control? · filters? · verify? · max_images? |
| /api/v1/memory/recall | 단기 + 장기 + 문맥 | user_id · query · limit? · context_limit? |
| /api/v1/memory/get | id 로 기억 한 건 | user_id · memory_id |
| /api/v1/memory/list | 저장소를 페이지 단위로 열람 | user_id · limit? · cursor? |
| /api/v1/memory/history | 최근 대화 | user_id |
| /api/v1/memory/stats | 기억 통계 | user_id |
| /api/v1/memory/supersede | 바뀐 사실 교체 | user_id · old_memory_id · new_content |
| /api/v1/memory/forget | 하나(또는 전체) 삭제 | user_id · memory_id? (생략 = 전체 삭제) |
| GET /api/v1/engram | 이 모델이 실행할 수 있는 엔그램 | (없음) |
| POST /api/v1/engram/run | 엔그램 하나 실행 | name · user_id · query · form? · tz? |
| GET /api/v1/models | 사용 가능한 모델 | (없음) |
쓰기 요청은
Idempotency-Key 헤더를 받습니다. 같은 키에 같은 본문이면 다시 저장하지 않고 첫 응답을 재생하며(10분), 같은 키에 다른 본문이면 422 로 답합니다. 2xx 만 캐시하므로 실패한 호출은 곧바로 다시 시도할 수 있습니다.# 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?"}'
실제 응답 - store
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}