> ## 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.

# List Disks

> List, search, and filter owned and active-saved Disks.

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

<ParamField query="search" type="string">
  Natural language search over owned Disks. Combines semantic embedding match with title/summary `ILIKE` fallback.
</ParamField>

<ParamField query="scope" type="string" default="all">
  Library scope for non-search lists: `all`, `owned`, `saved`, `private`, or `published`.
</ParamField>

<ParamField query="category" type="string">
  Filter to one category id (e.g. `technology`, `philosophy`, `spirituality`). Ignored when `search` is set.
</ParamField>

<ParamField query="tag" type="string">
  Filter to Disks containing this exact tag name. Applied after the search/category step.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Page size. Capped at `100`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset. Ignored when `search` is set.
</ParamField>

### Examples

```bash theme={null}
# 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

<ResponseField name="disks" type="array">
  <Expandable title="Disk summary">
    <ResponseField name="public_id" type="string" />

    <ResponseField name="title" type="string" />

    <ResponseField name="summary" type="string" />

    <ResponseField name="category" type="string" />

    <ResponseField name="visibility" type="string">`private` or `published` for active rows. Present on non-search list rows.</ResponseField>
    <ResponseField name="relationship" type="string">`owned` or `saved`.</ResponseField>
    <ResponseField name="owner_user_id" type="string">Owner UUID. Present on non-search list rows.</ResponseField>
    <ResponseField name="owner_display_name" type="string | null">Owner display name when available. Present on non-search list rows.</ResponseField>

    <ResponseField name="tags" type="string[]" />

    <ResponseField name="word_count" type="integer">May be omitted on semantic `search` rows.</ResponseField>
    <ResponseField name="saved_at" type="string | null">ISO 8601 timestamp for saved Disks. Present on non-search list rows.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp. May be omitted on semantic `search` rows.</ResponseField>
    <ResponseField name="similarity" type="number">Only present on `search` responses.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scope" type="string">
  The effective scope. Search responses always return `owned`.
</ResponseField>

<ResponseField name="total" type="integer">
  Total matching count (best-effort; equals `disks.length` for search responses).
</ResponseField>

```json theme={null}
{
  "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
}
```