Senso Documentation — The Trusted AI Answer

Every call to the Senso API needs an API key, and every key acts on one organization. This guide is a complete retrieval-augmented generation (RAG) round trip. You add a document, Senso processes it, and a question comes back with an answer written from your documents and the passages it used. There is nothing for you to set up or run.

Before you begin

You need a Senso organization and an API key. An admin can create a key on the API Keys page. Put it in an environment variable, so it stays out of your commands and your shell history:

bash

export SENSO_API_KEY="tgr_..."

Every request below goes to https://apiv2.senso.ai/api/v1 and sends the key in the X-API-Key header.

Send your first API request

1. Check your key

Ask which organization the key belongs to:

bash

curl "https://apiv2.senso.ai/api/v1/org/me" \
  -H "X-API-Key: $SENSO_API_KEY"

If the key works, you get your organization back:

json

{
  "org_id": "2b7e4f1c-8a3d-4c6e-9f5b-0d1e2f3a4b5c",
  "name": "Acme",
  "slug": "acme-1234",
  "is_free_tier": true
}

The response has more fields than this. A 401 means the key is missing, wrong, expired or revoked.

2. Add a document

Send some text to your knowledge base:

bash

curl -X POST "https://apiv2.senso.ai/api/v1/org/kb/raw" \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "text": "Customers can request a full refund within 30 days of purchase."
  }'

Senso answers 202 Accepted and processes the document in the background:

json

{
  "id": "6c1f2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b",
  "kb_node_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "type": "raw",
  "title": "Refund policy",
  "processing_status": "processing"
}

Keep the kb_node_id. You need it in the next step.

Senso does not store the same text twice. If you run this step again, or your organization already has this exact text, you get 409 Conflict. Change the text, or delete the first copy.

3. Wait for it to be ready

A document can be searched once it has been processed. Check on it with its kb_node_id:

bash

curl "https://apiv2.senso.ai/api/v1/org/kb/nodes/9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b" \
  -H "X-API-Key: $SENSO_API_KEY"

Poll this every 5 seconds until content.processing_status is complete. A short document is usually ready within a few seconds:

json

{
  "kb_node_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "type": "content",
  "name": "Refund policy",
  "content": {
    "processing_status": "complete"
  }
}

If it says failed, the error_code beside it says why.

4. Ask a question

Search your knowledge base:

bash

curl -X POST "https://apiv2.senso.ai/api/v1/org/search" \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do customers have to ask for a refund?"}'

You get an answer built from your documents, written in markdown, and the passages it came from:

json

{
  "query": "How long do customers have to ask for a refund?",
  "answer": "Customers have **30 days from the date of purchase** to request a full refund.",
  "results": [
    {
      "content_id": "6c1f2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b",
      "title": "Refund policy",
      "chunk_text": "Customers can request a full refund within 30 days of purchase.",
      "score": 0.87,
      "rank": 1
    }
  ],
  "total_results": 1
}

Each result's content_id is the id from step 2, so every answer can be traced back to the document it came from. Adding documents and searching both use credits. A 402 means you have run out.

5. Use your own model

To write the answer with your own model, ask Senso for the passages only:

bash

curl -X POST "https://apiv2.senso.ai/api/v1/org/search/context" \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do customers have to ask for a refund?"}'

You get the same retrieval as step 4, with no answer:

class="code-card-lang">json

{ "query": "How long do customers have to ask for a refund?", "search_type": "hybrid", "results": [ { "content_chunk_id": "4d3c2b1a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "content_id": "6c1f2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b", "kb_node_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "version_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "chunk_index": 0, "chunk_text": "Customers can request a full refund within 30 days of purchase.", "score": 0.875, "rank": 1, "title": "Refund policy", "vector_id": "6c1f2a9e-3b4d-4e8f-9a7b-1c2d3e4f5a6b_0", "inclusion_reason": "matched", "source_type": "raw", "content_type": "text/markdown", "retrieval": { "vector": { "score": 0.664, "rank": 1 }, "lexical": { "score": 2.913, "rank": 1 } } } ], "total_results": 1, "max_results": 5 }

Put each result's chunk_text into your model's prompt as context, and keep its content_id so your answer can cite the document it came from. This call uses credits like step 4.

Do the same with the CLI

The Senso CLI makes the same requests:

bash

senso whoami
senso kb create-raw --data '{"title": "Refund policy", "text": "Customers can request a full refund within 30 days of purchase."}'
senso kb get <kb_node_id>
senso search "How long do customers have to ask for a refund?"
senso search context "How long do customers have to ask for a refund?"

Store your API key

Keep keys on a server, in an environment variable or a secrets manager, and never in browser code or source control. API Keys covers restricting a key to part of your knowledge base, rotating it and revoking it.

Next steps

API Reference — Every endpoint, with request and response shapes
API Keys — Create, restrict, rotate and revoke keys
Errors — Every status the API returns, and what to do about it
Limits — Rate limits and pagination