Skip to main content

Ingest

The ingest endpoints allow running tools to write structured data back into Alexandria's session memory. They are exclusively for tools — not human users or agents. The orchestrator issues tool JWTs to tools at invocation time.

Authentication: tool JWT required (issued by orchestrator). All three endpoints return 401 if the token is missing or is not a tool token.

POST /v1/ingest/tool_result​

Store a tool execution result in session memory. The result is appended as an assistant turn in the conversation history.

Request

{
  "session_id": "my-session",
  "content": "Search results: Paris is the capital of France.",
  "tool_name": "web_search"
}

session_id and content are required. tool_name is informational and stored for retrieval context.

Response 201

{ "ok": true }

POST /v1/ingest/note​

Store a structured note in session memory. Notes persist separately from conversation turns and are retrievable via /v1/ingest/history.

{
  "session_id": "my-session",
  "note_type": "observation",
  "content": "The user prefers concise answers."
}

session_id and content are required. note_type defaults to "general".

Response 201

{
  "id": "01HXZ...",
  "agent_id": "researcher",
  "session_id": "my-session",
  "note_type": "observation",
  "content": "The user prefers concise answers.",
  "created_at": "2026-01-15T14:32:05Z"
}

GET /v1/ingest/history​

Retrieve all notes stored by the calling tool for a session.

Query params

  • session_id (required)

Response 200 — array of note objects.

curl "http://localhost:8080/v1/ingest/history?session_id=my-session" \
  -H "Authorization: Bearer $TOOL_TOKEN" | jq .

Notes on the tool JWT​

The tool JWT is issued by the Rust orchestrator when a tool is invoked. It carries:

  • AgentID — the agent that invoked the tool
  • UserID — the originating user
  • TokenType: "tool"

The ingest endpoints use these claims to scope the data appropriately. Tools cannot access data from other agents' sessions.