Skip to main content
POST
/
api
/
v1
/
search
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,
      "section_text": "<string>",
      "snippet": "<string>",
      "key_points": [
        "<string>"
      ],
      "redacted": true,
      "similarity": 123
    }
  ]
}
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

​
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.
{
  "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: 
{
  "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

StatusCodeMeaning
400—Missing query field
401unauthorizedBad / missing API key
429rate_limit_exceeded>100 req/min
500search_failed / internal_errorEmbedding or RPC failed