Retrieve Knowledge

Searches the embedded knowledge base of a project using semantic and keyword hybrid search. Returns relevant content grounded in the project data, along with citations. Optionally applies LLM-based reranking for improved relevance.

Embeddings can contain any form of content from a project — documents, labels, images, and more.

Endpoint

POST /api/v1/memory/retrieve

Authentication

All requests require a valid API token. You can generate an API token at https://account.deon.cloud/account/api-tokens. Use the DeonApiKey scheme in the Authorization header:

Authorization: DeonApiKey <your-api-token>

Request Body

Property	Type	Required	Default	Description
projectId	string (GUID)	Yes	—	The ID of the project to search.
query	string	Yes	—	The search query. Used for semantic and keyword matching against the knowledge base.
keywords	string[]	No	null	Optional keywords to refine the search.
maxResults	number	No	20	Maximum number of results to return. Must be ≤ 50 when postProcess is true.
postProcess	boolean	No	false	When true, applies LLM-based reranking by feeding the vector database results into a language model to adjust relevance scores.
itemIds	string[]	No	null	Optional list of item IDs to restrict the search to specific items.
agentConfigId	string	No	"default"	The agent configuration to use for retrieval.

Response

A successful response returns an AnswerResponse object:

Property	Type	Description
answer	string	The result grounded in the retrieved content. If postProcess is true, this will be an AI-generated answer. Otherwise, it will be a raw concatenation of the retrieved content.
citations	CitationReference[]	List of citation references supporting the answer. May be null if no citations are available.

CitationReference

Property	Type	Description
id	string	The ID of the cited source.
index	number	The citation index (used for ordering references).
relevance	number	Relevance score of the citation.
chunk	string	The content chunk that was matched. May be null.
projectId	string	The project ID the citation belongs to. May be null.

Examples

curl

curl -X POST "https://api.deon.cloud/api/v1/memory/retrieve" \
  -H "Authorization: DeonApiKey <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "query": "What are the main risks identified?",
    "keywords": ["risk", "mitigation"],
    "maxResults": 10,
    "postProcess": true
  }'

JavaScript

const response = await fetch(
  "https://api.deon.cloud/api/v1/memory/retrieve",
  {
    method: "POST",
    headers: {
      Authorization: `DeonApiKey ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      projectId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      query: "What are the main risks identified?",
      keywords: ["risk", "mitigation"],
      maxResults: 10,
      postProcess: true,
    }),
  }
);

const data = await response.json();
console.log(data.answer);
console.log(data.citations);

Response

{
  "answer": "The main risks identified include supply chain disruptions, regulatory changes, and cybersecurity threats. According to the project documentation...",
  "citations": [
    {
      "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "index": 1,
      "relevance": 0.95,
      "chunk": "Supply chain disruptions have been flagged as a critical risk...",
      "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
      "index": 2,
      "relevance": 0.87,
      "chunk": "Regulatory changes in the EU market pose significant challenges...",
      "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Filtering by Item IDs

You can restrict the search to specific items by providing an array of item IDs. This is useful when you want to query only a subset of the project's embedded content.

curl -X POST "https://api.deon.cloud/api/v1/memory/retrieve" \
  -H "Authorization: DeonApiKey <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "query": "Summarize the key findings",
    "itemIds": [
      "11111111-1111-1111-1111-111111111111",
      "22222222-2222-2222-2222-222222222222"
    ]
  }'

Error Handling

HTTP Status	Reason	Description
400	Missing Query	The query field is empty or missing.
400	MaxResults Exceeded	maxResults is greater than 50 when postProcess is true.
400	Retrieval Failed	An error occurred during knowledge retrieval.
403	Forbidden	User does not have access to the project.