> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skilldiscs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Knowledge

> Semantic search across every section of every owned Disk.

Returns the top-K matching sections ranked by vector similarity over Gemini embeddings. Current production search is scoped to **owned Disks only**.

Search responses follow the same redaction policy as Disk reads. Owner-private hits include `section_text`; redacted hits include `snippet`.

## Request

<ParamField body="query" type="string" required>
  Natural language query. Trimmed to the first 1000 characters before embedding.
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Maximum number of section hits returned. Capped at 25.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://skilldiscs.com/api/v1/search \
  -H "Authorization: Bearer sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "how does diffusion work in transformers", "limit": 5}'
```

## Response

<ResponseField name="results" type="array">
  Each hit references a single section inside one of your Disks.

  <Expandable title="Section hit">
    <ResponseField name="disk_public_id" type="string">Short URL-safe ID of the parent Disk.</ResponseField>
    <ResponseField name="disk_title" type="string">Title of the parent Disk.</ResponseField>
    <ResponseField name="section_index" type="integer">Zero-based section position within the Disk.</ResponseField>
    <ResponseField name="section_text" type="string">Full matched section text. Present only when `redacted` is `false`.</ResponseField>
    <ResponseField name="snippet" type="string">Bounded excerpt around the match. Present only when `redacted` is `true`.</ResponseField>
    <ResponseField name="key_points" type="string[]">AI-extracted key points for the matched section.</ResponseField>
    <ResponseField name="redacted" type="boolean">Whether verbatim section text was withheld.</ResponseField>
    <ResponseField name="similarity" type="number">Cosine similarity score, `0.0`–`1.0`.</ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "results": [
    {
      "disk_public_id": "abc123",
      "disk_title": "Attention Is All You Need — Annotated",
      "section_index": 4,
      "snippet": "Self-attention computes a weighted sum...",
      "key_points": ["Self-attention lets each token attend to every other token."],
      "redacted": true,
      "similarity": 0.91
    }
  ]
}
```

For an owner-private Disk, the same hit shape uses `section_text`:

```json theme={null}
{
  "results": [
    {
      "disk_public_id": "abc123",
      "disk_title": "Private Research Notes",
      "section_index": 1,
      "section_text": "Self-attention computes a weighted sum...",
      "key_points": ["Self-attention combines token representations by learned relevance."],
      "redacted": false,
      "similarity": 0.91
    }
  ]
}
```

## Errors

| Status | Code                               | Meaning                 |
| ------ | ---------------------------------- | ----------------------- |
| `400`  | —                                  | Missing `query` field   |
| `401`  | `unauthorized`                     | Bad / missing API key   |
| `429`  | `rate_limit_exceeded`              | >100 req/min            |
| `500`  | `search_failed` / `internal_error` | Embedding or RPC failed |