Skip to content

API.md

Latest commit

 

History

History
262 lines (191 loc) · 5.23 KB

API.md

File metadata and controls

262 lines (191 loc) · 5.23 KB

API Reference

This document describes every REST endpoint exposed by engram. All endpoints are served at http://localhost:3000 by default.

method path description
POST /sessions create a new session
POST /sessions/{session_id}/messages add a message
GET /sessions/{session_id}/context get assembled context
POST /sessions/{session_id}/search semantic search over long-term memory
DELETE /sessions/{session_id} delete a session and all its memories
PUT /sessions/{session_id}/core-memory add a core memory fact
GET /health health check
GET /metrics Prometheus metrics
GET /api-docs/openapi.json OpenAPI specification
GET /swagger-ui/ Swagger UI

POST /sessions

create a new session.

request body: none

success response:

  • status: 200
  • body:
{
  "session_id": "b1e2c3d4-5678-1234-9abc-def012345678"
}

error responses:

  • 500: internal server error

example:

curl -X POST http://localhost:3000/sessions

POST /sessions/{session_id}/messages

add a message to a session.

path parameters:

  • session_id (string): session identifier

request body:

{
  "id": "optional-client-generated-uuid",
  "role": "user",
  "content": "hello, what is rust?"
}

id is optional. role and content are required.

success response:

  • status: 204 (no content)

error responses:

  • 400: invalid request body
  • 422: missing required fields
  • 500: failed to store the message
  • 503: embedding queue unavailable

example:

curl -X POST http://localhost:3000/sessions/{session_id}/messages \
  -H 'content-type: application/json' \
  -d '{"role":"user","content":"hello, what is rust?"}'

GET /sessions/{session_id}/context

get the assembled context for a session.

path parameters:

  • session_id (string): session identifier

query parameters:

  • max_tokens (integer, optional, default: 8000): max tokens for context
  • similarity_threshold (float, optional, default: 0.7): min similarity for long-term memories
  • long_term_top_k (integer, optional, default: 10): max number of long-term memories

success response:

  • status: 200
  • body:
{
  "context": "core memories:\n- user name is alex\n\nconversation:\nuser: hello\n..."
}

error responses:

  • 400: invalid query parameters
  • 404: session not found
  • 500: failed to assemble context

example:

curl http://localhost:3000/sessions/{session_id}/context

POST /sessions/{session_id}/search

semantic search over long-term memory.

path parameters:

  • session_id (string): session identifier

request body:

{
  "query": "rust async",
  "top_k": 5
}

Both query and top_k are required.

success response:

  • status: 200
  • body:
{
  "results": [
    { "text": "...", "score": 0.92 }
  ]
}

error responses:

  • 400: invalid request body
  • 500: failed to search session memory

example:

curl -X POST http://localhost:3000/sessions/{session_id}/search \
  -H 'content-type: application/json' \
  -d '{"query":"rust async","top_k":5}'

DELETE /sessions/{session_id}

delete a session and all its memories.

path parameters:

  • session_id (string): session identifier

success response:

  • status: 204 (no content)

error responses:

  • 500: failed to delete session

example:

curl -X DELETE http://localhost:3000/sessions/{session_id}

PUT /sessions/{session_id}/core-memory

add a core memory fact to a session.

path parameters:

  • session_id (string): session identifier

request body:

{
  "fact": "user prefers dark mode"
}

fact is required and must not be empty.

success response:

  • status: 204 (no content)

error responses:

  • 400: missing or empty fact
  • 500: failed to add core memory

example:

curl -X PUT http://localhost:3000/sessions/{session_id}/core-memory \
  -H 'content-type: application/json' \
  -d '{"fact":"user prefers dark mode"}'

GET /health

health check endpoint.

success response:

  • status: 200

example:

curl http://localhost:3000/health

GET /metrics

Prometheus metrics endpoint.

success response:

  • status: 200
  • body: prometheus text format

example:

curl http://localhost:3000/metrics

GET /api-docs/openapi.json

OpenAPI specification (JSON).

success response:

  • status: 200
  • body: openapi json

example:

curl http://localhost:3000/api-docs/openapi.json | jq

GET /swagger-ui/

Swagger UI for interactive API docs.

success response:

  • status: 200
  • body: html

example:

curl http://localhost:3000/swagger-ui/