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>

Prerequisites

Retrieval only searches content that has already been analysed and imported into the knowledge base. A project that has never been analysed returns no content, and there is no separate error for that case — see Empty Results below.

Results are scoped by (UserId, MapId, TenantId), not by project alone. Two consequences:

• The analysis must have been run by the same user the API token belongs to. A project analysed by a colleague is not retrievable for you, even though the project itself is readable.
• The analysis must have been run under the same tenant as the request. Requests carry the tenant in the X-Tenant-Id header; an absent header means the default tenant. A project analysed while a different tenant was selected returns nothing.

Use Knowledge Status to check the precondition before querying — it reports whether anything is indexed for you and, if not, whether the cause is a missing analysis or a tenant mismatch.

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.

Empty Results

"Nothing was found" is not an error. When no content matches, the endpoint returns 200 OK with an empty citations array and this canned answer:

{
  "answer": "I'm sorry, I don't have enough information to answer that question.",
  "citations": []
}

That exact response covers three different situations, which are indistinguishable from the response alone:

1. The project has never been analysed.
2. The project was analysed, but by another user or under another tenant — see Prerequisites.
3. The project is indexed, and this particular query simply has no match.

tip

Call Knowledge Status to tell them apart. indexed: false means cases 1 or 2 — and registeredInUserIndex then says which. indexed: true means case 3, so rephrasing the query is the right next step.

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.

Note that a project which is not indexed for the caller is not in this table: it returns 200 with the canned answer, as described under Empty Results.