Skip to content

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.

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:

Terminal window
cortex login
cortex ingest ./docs --kb <knowledge-space-id> --wait
cortex 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.

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:

Terminal window
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.

The TypeScript package is @canopy/cortex-sdk:

Terminal window
npm install @canopy/cortex-sdk
import { 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.

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.

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:

Terminal window
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 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." }
);

@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 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.

  • Cortex CLI: cortex --help lists 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.