Skip to main content
GET
/
api
/
v1
/
disks
List Disks
curl --request GET \
  --url https://api.example.com/api/v1/disks
{
  "disks": [
    {
      "public_id": "<string>",
      "title": "<string>",
      "summary": "<string>",
      "category": "<string>",
      "visibility": "<string>",
      "relationship": "<string>",
      "owner_user_id": "<string>",
      "owner_display_name": {},
      "tags": [
        "<string>"
      ],
      "word_count": 123,
      "saved_at": {},
      "created_at": "<string>",
      "similarity": 123
    }
  ],
  "scope": "<string>",
  "total": 123
}
Returns a paginated list of owned and active-saved Disks, optionally narrowed by scope, category, or tag. When search is set, current production behavior searches owned Disks only and returns a slimmer result shape.

​
Query parameters

​
search
string
Natural language search over owned Disks. Combines semantic embedding match with title/summary ILIKE fallback.
​
scope
string
default:"all"
Library scope for non-search lists: all, owned, saved, private, or published.
​
category
string
Filter to one category id (e.g. technology, philosophy, spirituality). Ignored when search is set.
​
tag
string
Filter to Disks containing this exact tag name. Applied after the search/category step.
​
limit
integer
default:"20"
Page size. Capped at 100.
​
offset
integer
default:"0"
Pagination offset. Ignored when search is set.

​
Examples

# Most recent
curl https://skilldiscs.com/api/v1/disks \
  -H "Authorization: Bearer sk_your_key_here"

# Search
curl "https://skilldiscs.com/api/v1/disks?search=machine+learning" \
  -H "Authorization: Bearer sk_your_key_here"

# Filter
curl "https://skilldiscs.com/api/v1/disks?scope=owned&category=spirituality&tag=meditation" \
  -H "Authorization: Bearer sk_your_key_here"

​
Response

​
disks
array
​
scope
string
The effective scope. Search responses always return owned.
​
total
integer
Total matching count (best-effort; equals disks.length for search responses).
{
  "disks": [
    {
      "public_id": "abc123",
      "title": "Feynman on Quantum Mechanics",
      "summary": "Introductory lecture distilled into 7 sections.",
      "category": "science",
      "visibility": "private",
      "relationship": "owned",
      "owner_user_id": "8fb1d0c2-08d1-46ef-a2f3-6bf241745e24",
      "owner_display_name": "Ada",
      "tags": ["physics", "quantum", "lectures"],
      "word_count": 4231,
      "saved_at": null,
      "created_at": "2026-04-12T08:14:09.000Z"
    }
  ],
  "scope": "all",
  "total": 124
}