Items

List Items

GET/api/items

Retrieve paginated items from the vault.

Query Parameters

Parameter	Type	Default	Description
`source_type`	string	—	Filter by source type (e.g., `twitter`, `youtube`)
`category`	string	—	Filter by category (e.g., `Tech`, `Design`)
`date_preset`	string	—	`today`, `week`, or `month`
`limit`	number	20	Max items per page (max 100)
`offset`	number	0	Pagination offset

Example

curl

curl "http://localhost:3106/api/items?source_type=youtube&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "items": [...],
  "total": 142
}

Get Item

GET/api/items/:id

Get a single item by ID.

curl

curl "http://localhost:3106/api/items/uuid-here" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Item

PATCH/api/items/:id

Update item fields. All fields are optional.

Body

{
  title?: string
  category?: string
  subcategories?: string[]
  tags?: string[]
  notes?: string
}

Example

curl

curl -X PATCH "http://localhost:3106/api/items/uuid-here" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"category": "Design", "tags": ["typography", "branding"]}'

Delete Item

DELETE/api/items/:id

Permanently delete an item from the vault.

curl

curl -X DELETE "http://localhost:3106/api/items/uuid-here" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{ "success": true }

GET/api/items/related

Find items similar to a given item using vector similarity (pgvector).

Query Parameters

Parameter	Type	Default	Description
`id`	string	—	Required. Source item ID
`limit`	number	4	Max related items (max 10)

curl

curl "http://localhost:3106/api/items/related?id=uuid-here&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns an empty array if the source item has no embedding or no similar items are found.

Item Counts

GET/api/items/counts

Get the count of items grouped by source type.

curl

curl "http://localhost:3106/api/items/counts" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "counts": {
    "article": 45,
    "youtube": 23,
    "twitter": 18,
    "pdf": 7
  },
  "total": 93
}

Status Codes (All Endpoints)

Code	Description
200	Success
201	Item created (POST)
400	Invalid request or validation error
401	Unauthorized
404	Item not found
500	Server error

On this page