# Send your first API request

Check your key, add a document to your knowledge base, and ask it a question, then retrieve the same passages for your own model.

Every call to the Senso API needs an [API key](https://docs.senso.ai/docs/api-keys), 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](https://docs.senso.ai/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`:

```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](https://docs.senso.ai/docs/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](https://docs.senso.ai/docs/api-keys) covers restricting a key to part of your knowledge base, rotating it and revoking it.

## Next steps

- [API Reference](https://docs.senso.ai/api-reference) — Every endpoint, with request and response shapes
- [API Keys](https://docs.senso.ai/docs/api-keys) — Create, restrict, rotate and revoke keys
- [Errors](https://docs.senso.ai/docs/errors) — Every status the API returns, and what to do about it
- [Limits](https://docs.senso.ai/docs/limits) — Rate limits and pagination