POST
/
v0
/
context
/
assemble
Build magical context for an agent turn (optionally extract & ingest).
curl --request POST \
  --url https://api.flumes.ai/v0/context/assemble \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "entity_id": "<string>",
  "namespace": "default",
  "turn": "<string>",
  "goal": "<string>",
  "budget": {
    "max_context_tokens": 1200
  },
  "policy": {
    "pii_redaction": "auto",
    "egress_rehydration": "none"
  },
  "retrieval": {
    "preset": "balanced",
    "weights": {
      "semantic": 0.45,
      "bm25": 0.25,
      "graph_prior": 0.15,
      "recency_decay": 0.1,
      "confidence": 0.05
    },
    "normalization": "minmax",
    "recency_half_life_days": 45,
    "top_k": 24,
    "diversity": {
      "enable": true,
      "max_per_predicate": 3,
      "max_per_source": 5
    },
    "predicate_boosts": {},
    "entity_boosts": [
      "<string>"
    ],
    "depth": 2,
    "rerank": {
      "enable": false
    }
  },
  "return": {
    "include": [
      "facts",
      "recent_events",
      "summary",
      "sources"
    ],
    "max_facts": 12,
    "max_events": 6,
    "include_scores": false,
    "include_raw_memories": false,
    "trace": false,
    "include_structured_facts": false,
    "include_raw_matches": false
  },
  "seed_context": {
    "memory_ids": [
      "<string>"
    ],
    "snippets": [
      "<string>"
    ]
  },
  "must_include": [
    "<string>"
  ],
  "ingest": {
    "extract": true,
    "store_turn": "event",
    "upsert_conflicts": "smart"
  }
}'
{
  "context": {
    "facts": [
      "<string>"
    ],
    "facts_struct": [
      {
        "memory_id": "<string>",
        "type": "<string>",
        "text": "<string>",
        "subject": "<string>",
        "predicate": "<string>",
        "object_text": "<string>",
        "object_num": 123,
        "object_type": "<string>",
        "unit": "<string>",
        "keys": [
          "<string>"
        ],
        "status": "<string>",
        "confidence": 123,
        "timestamp": "2023-11-07T05:31:56Z",
        "valid_from": "2023-11-07T05:31:56Z",
        "valid_to": "2023-11-07T05:31:56Z",
        "score": 123,
        "metadata": {},
        "tags": [
          "<string>"
        ],
        "provenance": {}
      }
    ],
    "recent_events": [
      "<string>"
    ],
    "summary": "<string>",
    "sources": [
      "<string>"
    ],
    "token_counts": {
      "planned": 123,
      "budget": 123,
      "dropped": 123
    },
    "budget_actions": [
      {
        "action": "<string>",
        "memory_id": "<string>",
        "notes": "<string>"
      }
    ]
  },
  "trace": {
    "summary": {
      "origin": "<string>",
      "tokens_out": 123
    },
    "budget": {
      "origin": "<string>",
      "chars_per_token": 123
    }
  },
  "extracted": {
    "entities": [
      {
        "entity_id": "<string>",
        "type": "<string>",
        "name": "<string>",
        "confidence": 0.5,
        "attributes": {}
      }
    ],
    "facts": [
      {
        "memory_id": "<string>",
        "org_id": "<string>",
        "namespace": "default",
        "agent_id": "<string>",
        "entity_id": "<string>",
        "type": "fact",
        "text": "<string>",
        "metadata": {},
        "tags": [
          "<string>"
        ],
        "timestamp": "2023-11-07T05:31:56Z",
        "archived": false,
        "sensitivity": "auto",
        "subject": "<string>",
        "predicate": "<string>",
        "object": "<string>",
        "object_type": "literal",
        "unit": "<string>",
        "keys": [
          "<string>"
        ],
        "valid_from": "2023-11-07T05:31:56Z",
        "valid_to": "2023-11-07T05:31:56Z",
        "confidence": 0.5,
        "status": "active",
        "provenance": {}
      }
    ],
    "upserts": [
      {
        "memory_id": "<string>",
        "action": "UPSERTED",
        "supersedes": [
          "<string>"
        ]
      }
    ],
    "matches": [
      {
        "memory_id": "<string>",
        "type": "<string>",
        "text": "<string>",
        "metadata": {},
        "score": 123,
        "score_components": {},
        "reason": [
          "<string>"
        ],
        "timestamp": "2023-11-07T05:31:56Z"
      }
    ],
    "retrieval_summary": {
      "weights_used": {
        "semantic": 0.45,
        "bm25": 0.25,
        "graph_prior": 0.15,
        "recency_decay": 0.1,
        "confidence": 0.05
      },
      "normalization": "<string>",
      "depth": 123,
      "candidate_counts": {
        "semantic": 123,
        "bm25": 123,
        "graph": 123,
        "union": 123,
        "after_filters": 123
      },
      "diversity_actions": {
        "clamped_by_predicate": 123,
        "clamped_by_source": 123
      },
      "degraded": true,
      "budget_cut_count": 123
    },
    "flags": {
      "degraded": false,
      "weights_renormalized": false
    },
    "cost": {
      "input_tokens": 0,
      "embedding": 0,
      "llm_tokens": 0,
      "retrieval_ops": 0
    },
    "redaction": {
      "applied": true,
      "rules": [
        "<string>"
      ]
    },
    "raw_memories": [
      {
        "memory_id": "<string>",
        "org_id": "<string>",
        "namespace": "<string>",
        "agent_id": "<string>",
        "entity_id": "<string>",
        "type": "fact",
        "text": "<string>",
        "metadata": {},
        "tags": [
          "<string>"
        ],
        "timestamp": "2023-11-07T05:31:56Z",
        "archived": true,
        "sensitivity": "none",
        "subject": "<string>",
        "predicate": "<string>",
        "object": "<string>",
        "object_type": "literal",
        "unit": "<string>",
        "keys": [
          "<string>"
        ],
        "valid_from": "2023-11-07T05:31:56Z",
        "valid_to": "2023-11-07T05:31:56Z",
        "confidence": 0.5,
        "status": "active",
        "provenance": {}
      }
    ],
    "request_id": "<string>"
  }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Flumes-Agent
string

Agent id within the org.

Maximum length: 128
Idempotency-Key
string

Idempotency key for safe retries (unique per org).

Maximum length: 128

Query Parameters

trace
boolean
default:false

Include verbose trace/debug fields.

Body

application/json

Response

200
application/json

Context + optional extraction/ingestion report

The response is of type object.