API Reference

Start with auth, then pick an endpoint.

Use this page to get to your first successful call.

What this page covers

This reference covers auth, request context, and the current Agent API endpoints.

Notice
Keep request IDs and app context when you report an API issue.

Issue a token first

Create a personal access token before you test any Agent API call.

1
Open `/login` and sign in with Google or magic link.
2
Go to Settings and open `Personal Access Tokens`.
3
Create a token with `read:clips` and `search:clips` for the full Agent API flow.
4
Save the token immediately because the plain text value is shown only once.

Current endpoint contracts

The current public Agent API has three operations.

Each section includes scopes, parameters, and request and response examples.

`search`

POST /api/v1/agent/search

Required scope: `search:clips`

Searches clips by query and returns ranked results with score metadata.

Input parameters

Name	Type	Required	Description	Notes
`query`	`string`	Yes	Search text used to rank matching clips.	Required. 1-500 chars. Example: `hybrid search ranking`.
`limit`	`integer`	No	Maximum number of ranked results to return.	Optional. Count. 1-50. Example: `3`.
`timeRangeDays`	`integer \| null`	No	Restricts the search window to the last N days.	Optional. Unit: days. 1-365. Example: `30`.
`clipTypes`	`clip_type[]`	No	Limits search to specific clip source types.	Optional. Example: `["shared_link", "web_selection"]`.

Request example

curl -sS \
  -X POST "$QUONTEXT_BASE_URL/api/v1/agent/search" \
  -H "Authorization: Bearer $QUONTEXT_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "hybrid search ranking",
    "limit": 3,
    "timeRangeDays": 30,
    "clipTypes": ["shared_link", "web_selection"]
  }'

Response example

{
  "query": "hybrid search ranking",
  "results": [
    {
      "clipId": "9f6af9bc-8b5a-41e8-bf44-4b95b9b312d2",
      "clipType": "shared_link",
      "status": "ready",
      "sourceTitle": "Hybrid Search Ranking",
      "sourceUrl": "https://example.com/hybrid-search-ranking",
      "previewText": "Ranking combines vector, text, and recency signals...",
      "annotation": {
        "memo": "Useful explanation of scoring tradeoffs",
        "intents": ["research"]
      },
      "capturedAt": "2026-04-07T10:15:00.000Z",
      "primaryAssetThumbnailUrl": null,
      "score": {
        "textScore": 0.82,
        "vectorScore": 0.79,
        "recencyScore": 0.43,
        "contextScore": 0.65,
        "combinedScore": 0.77
      }
    }
  ],
  "emptyReason": null
}

Behavior notes

Results include score metadata so downstream agents can inspect ranking signals.
`results[].clipId` can be passed directly into `get_clip`.
Use this path when the task depends on query matching rather than recent retrieval.

`get_clip`

GET /api/v1/agent/clips/{clipId}

Required scope: `read:clips`

Fetches one clip in detail, including source, content, annotation, and assets.

Input parameters

Name	Type	Required	Description	Notes
`clipId`	`string`	Yes	Identifier of the clip to fetch in detail.	Required. Use a value returned by `search` or `list_clips`.

Request example

curl -sS \
  -H "Authorization: Bearer $QUONTEXT_PAT" \
  "$QUONTEXT_BASE_URL/api/v1/agent/clips/$CLIP_ID"

Response example

{
  "clipId": "9f6af9bc-8b5a-41e8-bf44-4b95b9b312d2",
  "clipType": "shared_link",
  "status": "ready",
  "capturedAt": "2026-04-07T10:15:00.000Z",
  "source": {
    "title": "Hybrid Search Ranking",
    "url": "https://example.com/hybrid-search-ranking",
    "author": null,
    "app": "browser",
    "domain": "example.com"
  },
  "content": {
    "rawText": null,
    "extractedText": "Ranking combines vector, text, and recency signals...",
    "selectedText": null,
    "previewText": "Ranking combines vector, text, and recency signals...",
    "selectionContextBefore": null,
    "selectionContextAfter": null
  },
  "annotation": {
    "memo": "Useful explanation of scoring tradeoffs",
    "intents": ["research"]
  },
  "assets": [],
  "derived": {
    "textEmbeddings": 1,
    "imageEmbeddings": 0
  },
  "relatedClips": []
}

Behavior notes

The response expands one clip into source, content, annotation, and asset metadata.
Use this path when an agent needs the full payload for one saved item.
A missing clip returns `not_found` instead of an empty result list.

`list_clips`

GET /api/v1/agent/clips

Required scope: `read:clips`

Lists clips in captured-time order for recent review and retrieval workflows.

Input parameters

Name	Type	Required	Description	Notes
`days`	`integer`	No	Returns clips captured within the last N days.	Optional. Unit: days. 1-365. Example: `7`.
`limit`	`integer`	No	Maximum number of clips to return.	Optional. Count. 1-50. Example: `5`.
`clip_types`	`clip_type[]`	No	Filters the list to one or more clip source types.	Optional. Repeat the query param or pass comma-separated values.

Request example

curl -sS \
  -H "Authorization: Bearer $QUONTEXT_PAT" \
  "$QUONTEXT_BASE_URL/api/v1/agent/clips?days=7&limit=5&clip_types=shared_link,web_selection"

Response example

{
  "days": 7,
  "limit": 5,
  "clipTypes": ["shared_link", "web_selection"],
  "results": [
    {
      "clipId": "9f6af9bc-8b5a-41e8-bf44-4b95b9b312d2",
      "clipType": "shared_link",
      "status": "ready",
      "sourceTitle": "Hybrid Search Ranking",
      "sourceUrl": "https://example.com/hybrid-search-ranking",
      "previewText": "Ranking combines vector, text, and recency signals...",
      "annotation": {
        "memo": "Useful explanation of scoring tradeoffs",
        "intents": ["research"]
      },
      "capturedAt": "2026-04-07T10:15:00.000Z",
      "primaryAssetThumbnailUrl": null
    }
  ]
}

Behavior notes

Results are ordered for recent retrieval rather than search ranking.
Use this when the task depends on the newest saved clips instead of query matching.
This path is the public replacement for the old `recent` naming.

`clipTypes` / `clip_types` values

`clipTypes` in `search` and `clip_types` in `list_clips` use the same enum values.

Value	Description
`web_selection`	A browser text selection captured from a web page.
`image`	An image-based capture created from an uploaded or shared image.
`shared_link`	A saved URL captured from a share flow or link action.
`note`	A plain text note captured directly by the user.
`pdf_excerpt`	A text excerpt captured from a PDF source.

What this page covers

Issue a token first

Open `/login` and sign in with Google or magic link.

Go to Settings and open `Personal Access Tokens`.

Create a token with `read:clips` and `search:clips` for the full Agent API flow.

Save the token immediately because the plain text value is shown only once.

Current endpoint contracts

`search`

Input parameters

Request example

Response example

Behavior notes

`get_clip`

Input parameters

Request example

Response example

Behavior notes

`list_clips`

Input parameters

Request example

Response example

Behavior notes

`clipTypes` / `clip_types` values

Related pages