Search Knowledge

curl --request POST \
  --url https://api.example.com/api/v1/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123
}
'

{
  "results": [
    {
      "disk_public_id": "<string>",
      "disk_title": "<string>",
      "section_index": 123,
      "snippet": "<string>",
      "similarity": 123
    }
  ]
}

POST

api

Search Knowledge

curl --request POST \
  --url https://api.example.com/api/v1/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123
}
'

{
  "results": [
    {
      "disk_public_id": "<string>",
      "disk_title": "<string>",
      "section_index": 123,
      "snippet": "<string>",
      "similarity": 123
    }
  ]
}

Returns the top-K matching sections ranked by vector similarity over Gemini embeddings.

Request

query

string

required

Natural language query. Trimmed to the first 1000 characters before embedding.

limit

integer

default:"10"

Maximum number of section hits returned. Capped at 25.

Example

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

results

array

Each hit references a single section inside one of your Disks.

Show Section hit

disk_public_id

string

Short URL-safe ID of the parent Disk.

disk_title

string

Title of the parent Disk.

section_index

integer

Zero-based section position within the Disk.

snippet

string

Section text (or excerpt around the match).

similarity

number

Cosine similarity score, 0.0–1.0.

{
  "results": [
    {
      "disk_public_id": "abc123",
      "disk_title": "Attention Is All You Need — Annotated",
      "section_index": 4,
      "snippet": "Self-attention computes a weighted sum...",
      "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

Introduction List Disks

⌘I

Reference

Documentation Index

​Request

​Example

​Response

​Errors

Request

Example

Response

Errors