Cortex developer guide
Cortex is Canopy’s AI product for managing knowledge, retrieval, assistants and related workflows. It can be used on its own. Host and Cortex can also be connected for selected workflows, but they have separate APIs and authorization checks.
First knowledge workflow
Section titled “First knowledge workflow”Create a Cortex project and knowledge space in the dashboard, then create an API key with access to that project. The key does not replace the organization and product-instance context required by individual routes. Use the Cortex CLI to upload a local directory and wait for ingestion:
cortex logincortex ingest ./docs --kb <knowledge-space-id> --waitcortex ask "What does the documentation say about deployments?" --kb <knowledge-space-id>Ingestion is asynchronous; check the job result before relying on newly uploaded content. See the Cortex CLI guide for setup, environment variables and MCP registration behavior.
Upload documents through the API
Section titled “Upload documents through the API”The CLI accepts PDF, Markdown and text files; for a direct API upload,
create an upload ingestion job and send one file to its general file route.
The route also accepts Word .docx files:
export CORTEX_API_URL="https://cortex.api.canopy.pm"export CORTEX_API_KEY="<your-api-key>"export CORTEX_PRODUCT_INSTANCE_ID="<your-product-instance-id>"export CORTEX_KNOWLEDGE_SPACE_ID="<your-knowledge-space-id>"
JOB=$(curl -fsS -X POST "$CORTEX_API_URL/ingestion-jobs" \ -H "Authorization: Bearer $CORTEX_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"product_instance_id\":$CORTEX_PRODUCT_INSTANCE_ID,\"knowledge_space_id\":$CORTEX_KNOWLEDGE_SPACE_ID,\"job_type\":\"upload\"}")JOB_ID=$(printf '%s' "$JOB" | jq -r .id)
curl -fsS -X POST \ "$CORTEX_API_URL/ingestion-jobs/$JOB_ID/documents/file?product_instance_id=$CORTEX_PRODUCT_INSTANCE_ID" \ -H "Authorization: Bearer $CORTEX_API_KEY" \ -F "file=@./handbook.md"Markdown, text and HTML files are limited to 512 KiB. DOCX files are limited
to 2 MiB compressed and 8 MiB when unpacked. Unsupported or unreadable files
return 415; oversized files return 413; supported files with no extracted
text return 422. The product-instance and knowledge-space IDs must belong to
the caller’s authorized scope. The dedicated /documents/pdf route remains
available for PDF-only integrations. The CLI uses the dedicated PDF route
for PDFs and the general file route for its supported text files. It currently
accepts .pdf, .txt, .md and .markdown, but does not expose the API’s
HTML or DOCX support. See the API contract
for current request and response schemas.
The deployed API exposes its generated OpenAPI reference at
https://cortex.api.canopy.pm/docs.
API and SDK
Section titled “API and SDK”The TypeScript package is @canopy/cortex-sdk:
npm install @canopy/cortex-sdkimport { createCortexSDK } from "@canopy/cortex-sdk";
const cortex = createCortexSDK({ apiKey: process.env.CORTEX_API_KEY, orgId: Number(process.env.CORTEX_ORG_ID),});
const productInstanceId = Number(process.env.CORTEX_PRODUCT_INSTANCE_ID);const spaces = await cortex.knowledgeSpaces.list(productInstanceId);
const answer = await cortex.knowledgeSpaces.ask( Number(process.env.CORTEX_KNOWLEDGE_SPACE_ID), "How do I rotate an API key?", { topK: 5 },);
console.log(answer.answer);for (const passage of answer.retrieved_chunks) { console.log(passage.document_title, passage.source_ref, passage.snippet);}orgId selects the X-Cortex-Org context. Resources such as knowledge
spaces also take the product-instance ID required by their API methods.
The API checks the caller’s membership and key scope; selecting an
organization or passing an ID does not grant access. The SDK package
manifest in this checkout declares version 0.17.0. Consult the package
registry for the release you install.
The SDK exposes typed resources for organizations, tenants, API keys, knowledge spaces, assistants, conversations, generated responses and streaming, ingestion jobs, sync sources, usage, webhooks, training, inference, retrieval evaluation sets, evaluation suites, agent runs, runtime state and platform features. This list is an orientation rather than a complete API parity claim. The exact public contract is the deployed Cortex OpenAPI document. The SDK does not expose a local-directory upload method; use a supported ingestion workflow such as the CLI, then use SDK methods to retrieve or ask questions. SDK support is not yet mechanically mapped to every public API operation.
Availability and access
Section titled “Availability and access”Cortex routes combine authentication, organization ownership, API-key
scope and platform feature checks. A route present in OpenAPI may still
be unavailable to a particular account or deployment. The platform
feature resolver is available at /platform-features/resolved; public
responses omit disabled and internal features. Consult the dashboard or
your account’s feature response when a route is unavailable.
The current feature manifest distinguishes these SDK resources:
| Capability | Manifest status | Availability notes |
|---|---|---|
| Knowledge spaces, assistants and conversations | GA, public | Enabled by default; organization membership, API-key scope and resource ownership still apply. |
Retrieval evaluation sets (eval-sets) |
Implemented, public API | Scores retrieval and refusal against a golden set; it is distinct from evaluation suites. Runs need the retrieval-evaluation worker. |
Evaluation suites (eval-suites) |
Generally available, public | Staff can switch the feature off. Check /platform-features/resolved before depending on it. |
| Agent runs and runtime state | Generally available, public | Staff can switch these features off. A queued agent run reports phase: unserved while no executor can take it yet, can be cancelled (cortex agent-runs cancel <run_id>, POST /agent-runs/{run_id}/cancel), and an agent run no executor can reach ends failed with the reason. Every run shows one phase with a waiting_reason, a reachability hint and, after a failure, a customer-safe failure; `cortex agent-runs show |
| Training and training datasets | Generally available, internal | Training runs on your own node or on Canopy’s GPUs; the routes are staff-visible in the manifest. |
| Freshdesk and Symphony workflows | Planned, internal | Staff-restricted in the feature manifest; not a generally available customer integration. |
The generated API reference can include routes that require a feature that is disabled for your deployment. The feature manifest, runtime feature response and authorization checks determine availability; the presence of an SDK wrapper does not grant access or promise general availability.
Evaluate retrieval quality
Section titled “Evaluate retrieval quality”eval-sets measures whether retrieval finds expected passages and whether
the evidence gate rejects unanswerable questions. It does not judge the
wording of generated answers. Upload a JSONL or CSV golden set, start a
run, then inspect its metrics:
cortex eval-sets upload golden.jsonl --kb <knowledge-space-id> --name "Support pilot"cortex eval-sets run <evaluation-set-id>cortex eval-sets show <run-id>The Cortex SDK supports listing sets, updating the weekly schedule, starting a run, and polling its results. Golden-set file upload remains a CLI workflow because the shared SDK HTTP client does not currently support multipart requests:
const evaluationSetId = Number(process.env.CORTEX_EVAL_SET_ID);if (!Number.isInteger(evaluationSetId) || evaluationSetId <= 0) { throw new Error("Set CORTEX_EVAL_SET_ID to an existing evaluation set ID");}const run = await cortex.evalSets.startRun(evaluationSetId, productInstanceId);const detail = await cortex.evalSets.getRun(run.id, productInstanceId);The run is asynchronous and remains pending until the retrieval_eval
worker processes it. The separate eval-suites API covers experimental
suite definitions and application/model evaluations; check its feature
availability before using it. A JSONL golden set has one object per line,
for example {"id":"q1","question":"How long do refunds take?","relevant":[{"source_ref":"refunds.md","chunk_index":0}]}.
Mark an unanswerable question with "answerable": false. Runs report
mean reciprocal rank, nDCG@5/10 and recall@5/10 for answerable questions,
plus refusal correctness and false-refusal rate for unanswerable and
answerable questions. Questions whose source document is no longer live
are reported as uncovered and excluded from scoring. This evaluates
retrieval and refusal behavior, not answer wording or whether a generated
claim is supported by its citation.
Knowledge and cited answers
Section titled “Knowledge and cited answers”Knowledge spaces hold source material used for retrieval. An assistant can be configured to use allowed spaces; the API returns retrieved passages and citation metadata with answers. Keep retrieval scoped to spaces the assistant is permitted to access. For endpoint details and current response fields, use the OpenAPI reference. The API checks route access and retrieval scope on each request.
To show matching passages without generating an answer, use
knowledgeSpaces.search(id, query, topK), which calls
POST /knowledge-spaces/{id}/search. It returns up to top_k passages
(1 to 20, default 8) from that one knowledge space, each with the document
title, source_ref, section, pages and a snippet of at most 700 characters,
and an evidence object whose sufficient field says whether the match is
strong enough to rely on. It calls no model, accepts a query of at most
1000 characters, and counts as one search in usage under the
knowledge_search source. A knowledge space that does not exist, is archived,
or belongs to another organization answers 404. Each organization may make
60 searches per minute; beyond that the API answers 429 with Retry-After.
Use the Documents SDK resource to search and page through indexed
documents. list() returns up to 50 rows by default and accepts a maximum
limit of 200; use count() when you need the total for the same filters.
The signed view URL expires after 15 minutes. Archive hides a document from
normal listings and removes its training-dataset links. setVisibility()
changes whether a document is public or tenant-private; setMinimumRole()
controls the lowest role that can read it. delete() removes the document
row and chunks, keeps saved citation text marked as removed, and returns
deletion counts. The stored file is removed when storage is configured and
no other document shares it; storage failures are reflected by
storage_object_removed: false. These operations still require the caller’s
document permissions.
const page = await cortex.documents.list(productInstanceId, { knowledgeSpaceId, search: "deployment", limit: 50, offset: 0,});For exact-match responses that should bypass retrieval and model inference,
the SDK can manage an assistant’s canned responses. Matching ignores case,
repeated whitespace, and trailing ?, !, or . punctuation; it does not
use fuzzy or semantic matching. If the assistant has a knowledge space,
optional citation chunk IDs must belong to it:
const canned = await cortex.assistants.createCannedResponse( assistantId, productInstanceId, { question: "What is the support window?", answer: "Weekdays, 09:00–17:00 UTC." });Streaming
Section titled “Streaming”@canopy/cortex-sdk includes the responses resource and typed stream
events. Streaming uses server-sent events; consume it with the SDK’s
streaming methods and handle terminal events and errors. Do not treat a
partial stream as a completed response.
For custom interfaces, conversations.createMessage() records a message; it
does not generate an answer. Use responses.create() or responses.stream()
for generation, then submit a message rating or citation helpfulness signal
when the user responds:
await cortex.conversations.submitMessageFeedback( conversationId, assistantMessageId, productInstanceId, 1);Symphony and Freshdesk support workflow
Section titled “Symphony and Freshdesk support workflow”Symphony is a support-oriented frontend in the repository. Its current implementation retrieves Freshdesk tickets, drafts a knowledge-grounded response with citations, and presents the draft for human review or editing; sending is a separate action. The Cortex feature manifest marks Symphony planned, and its login page can show a waitlist depending on the build setting. The separate Freshdesk API feature is planned, internal and staff-restricted. This code is an implementation example, not a generally available customer app or Freshdesk integration, and not a supported third-party framework.
Further references
Section titled “Further references”- Cortex CLI:
cortex --helplists the commands available in the installed release. - Cortex MCP server: tool availability depends on the configured server and account permissions.
- Host and Cortex SDK reference For command-line workflows, see the Cortex CLI guide.