List cards

GET/v1/cards

Authorization

AuthorizationBearer token (OAuth access token or teakapi_ API key) · headerrequired

Bearer token. Accepts either an OAuth 2.0 access token (obtained via browser sign-in; expires after 1 hour and is refreshable) or a teakapi_ API key.

Query parameters

qstring

Search text with optional qualifiers: tag:design or #design, type:link, is:fav, is:archived, site:github.com, folder:"Reading list", like:<cardId> (the cards closest in meaning to that card), mood:"moody brutalist" (images by mood), price:<100 (also >, <=, >= and =, on the amount in any currency; only links with a price match) and "quoted phrases". Qualifiers combine with the other parameters; several price: bounds make a range. Cards tagged secret or hidden (isHidden) are left out of every list unless the search names one of those tags: q=#secret, q=tag:hidden or tag=secret. The plain word secret does not show them.

similarTostring

A card id: only the cards closest to it in meaning, of any type, never the card itself (the same as like:<id> in q). Other parameters narrow them and sort orders them. A malformed id returns 400 INVALID_INPUT; a card in Trash or not found returns no items with similarity: "unavailable".

modestring

How q finds cards: hybrid (default) matches words and meaning, so cozy reading nook also finds a photo of an armchair by a window; keyword matches words only; semantic matches meaning only. Filters, qualifiers and sort apply in every mode. The response's searchMode says which ran.

default: "hybrid"

Allowed:hybridkeywordsemantic

limitinteger

cursorstring

sortstring

Order by the date each card was saved (createdAt, which keeps an imported card's original date): newest (default) or oldest. Or shuffle: a stable random order picked by shuffleSeed. A search, tag or folder shuffles its matches (a search its best 400, a tag or folder its newest 2,000). Or relevance (Best match), with q: the search's top 64 results by how well they match its words, then the rest in search order. Without q it is newest. The response's relevanceRanked says whether the top results were scored; the first page decides, and every later page keeps its order.

Allowed:newestoldestrelevanceshuffle

shuffleSeedinteger

Required with sort=shuffle: a whole number from 0 to 2147483647. The same seed gives the same order on every page and device; pick a new one to reshuffle. A cursor only works with the seed that issued it.

min 0 · max 2147483647

typestring[]

Repeat to match any selected card type, for example type=image&type=link.

tagstring

favoritedboolean

trashedboolean

List only cards in Trash when true.

folderstring

Only cards in this folder; for a smart folder, the cards its search matches (combined with q). An unknown folder returns 404.

archivedstring

Archived cards to list: exclude (the default) leaves them out, only lists just them, include lists them with the rest. Trash lists every trashed card whatever this says.

Allowed:excludeonlyinclude

stylestring[]

Repeat to match any selected value within this filter.

huestring[]

Repeat to match any selected value within this filter.

hexstring[]

Repeat to match any selected value within this filter.

createdAfternumber

createdBeforenumber

includestring

Comma-separated values: content, metadata, processing

Responses

200

Paginated card list

itemsCardListItem[]required

Show properties

Array of CardListItem

aiSummarystring | null

aiTagsstring[]required

aiTranscriptstring | null

appUrlstring<uri>required

compactUrlstring | null

256px rendition URL for small cards; present for image uploads.

contentstring

colorsobject[]

Show properties

Array of object

hexstringrequired

namestring

createdAtnumberrequired

detailUrlstring | null

fileNamestring | null

fileSizenumber | null

mimeTypestring | null

fileExtensionstring | null

fileKindstring | null

fileLanguagestring | null

filePreviewobject | null

fileHeightnumber | null

fileWidthnumber | null

audioWaveformobject | null

Audio bar heights from 0 to 100: 45 for a grid card and 200 for a player. Null for other cards and audio saved before waveforms.

Show properties

detailnumber[]required

gridnumber[]required

videoScrubobject | null

A horizontal JPEG strip of evenly spaced video frames for hover previews, frames * frameWidth wide. The URL is signed and expires. Null for other cards and videos saved before scrub strips.

Show properties

frameHeightnumberrequired

frameWidthnumberrequired

framesnumberrequired

urlstringrequired

fileUrlstring | null

idstringrequired

isDeletedboolean

isArchivedbooleanrequired

Archived cards are hidden from the library and listings unless you ask for them with archived.

folderIdsstring[]

Ids of the folders the card is in (at most 50).

isFavoritedbooleanrequired

isHiddenboolean

True when one of the card's tags is secret or hidden (any case). Hidden cards are left out of every list and search unless the search names one of those tags, as q=#secret, q=tag:hidden or tag=secret. Getting the card by id, /v1/cards/changes and exports still include it. Read-only: change the tags to change it.

linkPreviewImageUrlstring | null

linkPreviewDescriptionstring | null

linkFactsobject[]

Show properties

Array of object

labelstringrequired

valuestringrequired

linkFaviconUrlstring | null

linkPreviewTitlestring | null

linkPriceobject | null

A product link's price, read from the page: amount in the page's currency and currency as an ISO 4217 code, or null when the page didn't say which. Null for cards without a price. price: in q compares amount.

Show properties

amountnumberrequired

currencystring | nullrequired

linkPreviewMediaobject[]

Show properties

Array of object

typestringrequired

Allowed:imagevideo

urlstringrequired

contentTypestring

widthnumber

heightnumber

posterUrlstring

posterContentTypestring

posterWidthnumber

posterHeightnumber

linkSiteNamestring | null

linkAuthorstring | null

linkPublisherstring | null

linkPublishedAtstring | null

metadataDescriptionstring | null

metadataTitlestring | null

notesstring | null

placeholderUrlstring | null

48px loading-placeholder rendition URL; present for image uploads.

metadataStatusstring | null

processingStatusobject | null

Per-stage processing state (classify, categorize, metadata, renderables, screenshot), or null once nothing is tracked.

screenshotUrlstring | null

sourceTitlestring | null

The title of the page the card was saved from, beside sourceUrl.

sourceUrlstring | null

The page the card was saved from, such as the page a quote was selected on. Set when the card is created; site: matches its host when the card has no url. Not the same as source, the free label sent at create.

tagsstring[]required

thumbnailOverriddenboolean

True when linkPreviewImageUrl is an image chosen for this link (PUT /v1/cards/{cardId}/thumbnail) rather than the one Teak found.

thumbnailUrlstring | null

typestringrequired

updatedAtnumberrequired

urlstring | null

pageInfoCardPageInforequired

Show properties

hasMorebooleanrequired

nextCursorstring | nullrequired

Opaque cursor for the next page, or null on the last page. Pages resume after the last item returned, so cards added or removed between requests never repeat or skip items. Pass it back unchanged with the same filters; an invalid cursor returns 400.

similaritystring

With similarTo, like: or mood:: pending while the card is still being read (try again in a moment), unavailable for a card in Trash or not found.

Allowed:okpendingunavailable

searchModestring

With q: how the search found cards. keyword when meaning search was not used: mode=keyword, no words to search by meaning, or the meaning service was slow, down or rate-limited.

Allowed:hybridkeywordsemantic

relevanceRankedboolean

With q and sort=relevance: whether the search's top results are ordered by how well they match. false when scoring was slow, failed, rate-limited, or AI is turned off for the account; the results then keep the search order.

400

Invalid request

codestringrequired

errorstringrequired

retryAtnumber | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (OAuth access token or teakapi_ API key)Remember on this deviceInclude my values in samples

Parameters

qquerySearch text with optional qualifiers: `tag:design` or `#design`, `type:link`, `is:fav`, `is:archived`, `site:github.com`, `folder:"Reading list"`, `like:<cardId>` (the cards closest in meaning to that card), `mood:"moody brutalist"` (images by mood), `price:<100` (also `>`, `<=`, `>=` and `=`, on the amount in any currency; only links with a price match) and `"quoted phrases"`. Qualifiers combine with the other parameters; several `price:` bounds make a range. Cards tagged `secret` or `hidden` (`isHidden`) are left out of every list unless the search names one of those tags: `q=#secret`, `q=tag:hidden` or `tag=secret`. The plain word `secret` does not show them.similarToqueryA card id: only the cards closest to it in meaning, of any type, never the card itself (the same as `like:<id>` in `q`). Other parameters narrow them and `sort` orders them. A malformed id returns `400 INVALID_INPUT`; a card in Trash or not found returns no items with `similarity: "unavailable"`.modequeryHow `q` finds cards: `hybrid` (default) matches words and meaning, so `cozy reading nook` also finds a photo of an armchair by a window; `keyword` matches words only; `semantic` matches meaning only. Filters, qualifiers and `sort` apply in every mode. The response's `searchMode` says which ran.limitquerycursorquerysortqueryOrder by the date each card was saved (`createdAt`, which keeps an imported card's original date): `newest` (default) or `oldest`. Or `shuffle`: a stable random order picked by `shuffleSeed`. A search, tag or folder shuffles its matches (a search its best 400, a tag or folder its newest 2,000). Or `relevance` (Best match), with `q`: the search's top 64 results by how well they match its words, then the rest in search order. Without `q` it is `newest`. The response's `relevanceRanked` says whether the top results were scored; the first page decides, and every later page keeps its order.shuffleSeedqueryRequired with `sort=shuffle`: a whole number from 0 to 2147483647. The same seed gives the same order on every page and device; pick a new one to reshuffle. A `cursor` only works with the seed that issued it.typequeryRepeat to match any selected card type, for example type=image&type=link.tagqueryfavoritedquerytrashedqueryList only cards in Trash when true.folderqueryOnly cards in this folder; for a smart folder, the cards its search matches (combined with `q`). An unknown folder returns 404.archivedqueryArchived cards to list: `exclude` (the default) leaves them out, `only` lists just them, `include` lists them with the rest. Trash lists every trashed card whatever this says.stylequeryRepeat to match any selected value within this filter.huequeryRepeat to match any selected value within this filter.hexqueryRepeat to match any selected value within this filter.createdAfterquerycreatedBeforequeryincludequeryComma-separated values: content, metadata, processing

Request

curl -X GET 'https://teakvault.com/api/v1/cards' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://teakvault.com/api/v1/cards", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

const response: Response = await fetch("https://teakvault.com/api/v1/cards", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://teakvault.com/api/v1/cards",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://teakvault.com/api/v1/cards", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Accept", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, _ := io.ReadAll(res.Body)
	fmt.Println(string(data))
}

require "net/http"

uri = URI("https://teakvault.com/api/v1/cards")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Accept"] = "application/json"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://teakvault.com/api/v1/cards',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
  ],
]);

$response = curl_exec($curl);

Response

{
  "items": [
    {
      "aiSummary": "string",
      "aiTags": [
        "string"
      ],
      "aiTranscript": "string",
      "appUrl": "http://example.com",
      "compactUrl": "string",
      "content": "string",
      "colors": [
        {
          "hex": "string",
          "name": "string"
        }
      ],
      "createdAt": 0,
      "detailUrl": "string",
      "fileName": "string",
      "fileSize": 0,
      "mimeType": "string",
      "fileExtension": "string",
      "fileKind": "string",
      "fileLanguage": "string",
      "filePreview": {},
      "fileHeight": 0,
      "fileWidth": 0,
      "audioWaveform": {
        "detail": [
          0
        ],
        "grid": [
          0
        ]
      },
      "videoScrub": {
        "frameHeight": 0,
        "frameWidth": 0,
        "frames": 0,
        "url": "string"
      },
      "fileUrl": "string",
      "id": "string",
      "isDeleted": true,
      "isArchived": true,
      "folderIds": [
        "string"
      ],
      "isFavorited": true,
      "isHidden": true,
      "linkPreviewImageUrl": "string",
      "linkPreviewDescription": "string",
      "linkFacts": [
        {
          "label": "string",
          "value": "string"
        }
      ],
      "linkFaviconUrl": "string",
      "linkPreviewTitle": "string",
      "linkPrice": {
        "amount": 0,
        "currency": "string"
      },
      "linkPreviewMedia": [
        {
          "type": "image",
          "url": "string",
          "contentType": "string",
          "width": 0,
          "height": 0,
          "posterUrl": "string",
          "posterContentType": "string",
          "posterWidth": 0,
          "posterHeight": 0
        }
      ],
      "linkSiteName": "string",
      "linkAuthor": "string",
      "linkPublisher": "string",
      "linkPublishedAt": "string",
      "metadataDescription": "string",
      "metadataTitle": "string",
      "notes": "string",
      "placeholderUrl": "string",
      "metadataStatus": "string",
      "processingStatus": {},
      "screenshotUrl": "string",
      "sourceTitle": "string",
      "sourceUrl": "string",
      "tags": [
        "string"
      ],
      "thumbnailOverridden": true,
      "thumbnailUrl": "string",
      "type": "string",
      "updatedAt": 0,
      "url": "string"
    }
  ],
  "pageInfo": {
    "hasMore": true,
    "nextCursor": "string"
  },
  "similarity": "ok",
  "searchMode": "hybrid",
  "relevanceRanked": true
}

{
  "code": "string",
  "error": "string",
  "retryAt": 0
}