Documentation

Real examples, not marketing copy.

Everything below reflects the actual Cortex API surface used during a support pilot: authentication, ingestion, cited queries, and the Freshdesk/Symphony integration.

Book a pilot Ask a question

Get an API key, make your first request.

API keys are issued from the Cortex dashboard once your pilot is set up. Every request authenticates with a bearer token scoped to your project.

quickstart.sh

curl https://api.cortex.canopy.pm/v1/models \
  -H "Authorization: Bearer crtx_sk_..."

2. Scoped API keys

Every key is scoped. Never org-wide by default.

readRead knowledge bases and documents. No chat, no ingestion.

chatAsk questions and start conversations. No document ingestion.

ingestUpload and manage documents. No chat access.

fullEvery operation. Use sparingly - prefer the narrowest scope an integration actually needs.

Create a separate key per integration - one for Symphony/Freshdesk, one for internal tooling, one for CI. Rotating or revoking one key never affects the others.

3. Ingestion example

Create a job, then upload a document.

Ingestion is two steps: create an ingestion job for your project and knowledge base, then upload the file against that job. PDF is supported today; more formats are on the roadmap.

ingest.sh

# 1. Create an ingestion job
curl -X POST https://api.cortex.canopy.pm/v1/ingestion-jobs \
  -H "Authorization: Bearer crtx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_instance_id": 123,
    "job_type": "pdf"
  }'
# -> { "id": 456, "status": "pending", ... }

# 2. Upload the file against that job
curl -X POST https://api.cortex.canopy.pm/v1/ingestion-jobs/456/documents/pdf \
  -H "Authorization: Bearer crtx_sk_..." \
  -F "file=@refund-policy.pdf"

4. Cited query example

Ask a question, get an answer with sources.

Query a knowledge base directly for a cited answer, or use the OpenAI-compatible chat completions endpoint if your code already talks to OpenAI.

ask.sh

curl -X POST https://api.cortex.canopy.pm/v1/knowledge-spaces/789/ask \
  -H "Authorization: Bearer crtx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is the refund policy?" }'

5. Citation response example

The shape of a cited answer.

response.json

{
  "answer": "Refunds are available within 30 days of purchase, provided the item is unused.",
  "citations": [
    {
      "document": "refund-policy.pdf",
      "section": "4.2 Eligibility",
      "excerpt": "Refunds are available within 30 days..."
    },
    {
      "document": "terms.md",
      "section": "8. Returns",
      "excerpt": "Items must be unused and in original packaging."
    }
  ]
}

6. Freshdesk / Symphony setup overview

Connect Freshdesk to Cortex.

Symphony is the Freshdesk workflow powered by Cortex. During onboarding we help you:

Register a Freshdesk webhook that fires on new and updated tickets.
Point that webhook at your Symphony endpoint, scoped to a Cortex API key with chat access.
Ingest your existing knowledge base, procedures, and resolved tickets.
Symphony calls Cortex's ask endpoint per ticket and posts a draft reply as a private note in Freshdesk.
An agent reviews the draft and citations, edits if needed, and sends the public reply from Freshdesk.

7. Webhooks

Get notified when ingestion or conversations change.

webhooks.sh

curl -X POST https://api.cortex.canopy.pm/v1/webhooks \
  -H "Authorization: Bearer crtx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/cortex",
    "events": ["ingestion.completed", "conversation.created"]
  }'

8. Streaming

Stream a response as it generates.

Conversation responses can stream over server-sent events, the same pattern OpenAI's streaming API uses - useful if you are building a live agent-facing view.

stream.py

from openai import OpenAI

client = OpenAI(base_url="https://api.cortex.canopy.pm/v1", api_key="crtx_sk_...")

stream = client.chat.completions.create(
    model="cortex-assistant",
    messages=[{"role": "user", "content": "What is the refund policy?"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

9. Errors, rate limits, and usage

What to expect when something goes wrong.

400Bad request - check the request body against the example below.

401Missing or invalid API key.

403The API key’s scope does not permit this operation.

404The knowledge base, document, or conversation does not exist in your project.

409A conflicting resource already exists (for example, a duplicate webhook).

429Too many requests. Back off and retry.

500Something failed on our side. If it persists, contact us with the request ID.

Error response shape

{ "detail": "Knowledge base not found" }

Rate limits are enforced per API key. Specific limits for your plan are shared during onboarding, since pilot and production traffic patterns differ. Usage (requests and token consumption) is visible in the dashboard, scoped to your project.

Security package

For due diligence and procurement.

Security posture, data privacy, DPA requests, and enterprise due-diligence answers are on a dedicated page, kept honest about what is confirmed versus planned.

Read security Data & Privacy

Canopy Host API

Canopy Host is a separate, secondary product with its own API for projects, environments, variables, builds, domains, teams, and GDPR export or erasure flows.

Request Host API docs