API Quickstart
Check your Teak API key and save your first card right from the docs, with a live Try it form and copyable samples in curl, JavaScript, Python, and more
Make your first two Teak API calls without leaving this page. Each request below has a Try it panel that sends a real request to your library, plus copyable samples in several languages.
1. Create an API key

In Teak, open Settings → Integrations → API keys and create a key. Keys start with teakapi_; treat one like a password. Paste it into the Authorization field of a Try it panel below, or export it for the code samples:
export TEAK_API_KEY=teakapi_...
2. Check your key
GET /v1/me returns the account the key belongs to. A 401 means the key is invalid or revoked.
/v1/meAuthorizationBearer token (OAuth access token or teakapi_ API key) · headerrequiredBearer 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.
Permanent Teak owner ID and current profile
dataobjectrequiredShow propertiesHide properties
idstringrequiredPermanent Teak owner ID
emailstring<email>requirednamestringcardCountnumberCards outside Trash
cardLimitnumber | nullFree plan card limit; null on Pro
planstringfreeprolocalestringrequiredThe account's Teak language, chosen in Settings: a BCP 47 code such as en, de or pt-BR. More languages may be added, so treat an unknown code as English.
settingsUrlstring<uri>Teak web Settings, where plan, billing, API keys and import live
Missing, invalid, expired, or revoked credential
Rate limit exceeded
Profile or authorization service unavailable
3. Save your first card
POST /v1/cards saves text or a URL. Teak detects links, quotes, and palettes automatically, then tags and summarizes the card in the background.
/v1/cardsAuthorizationBearer token (OAuth access token or teakapi_ API key) · headerrequiredBearer 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.
application/jsoncardTypestringOptional explicit card type. Text content is stored as raw Markdown without normalization. When omitted, Teak keeps automatic URL, quote, and palette classification. Uploaded file types are inferred from fileName and mimeType. image, video, audio, and document need an uploaded file (fileKey); palette needs at least one readable color in content, notes, or tags.
textlinkimagevideoaudiodocumentpalettequotecontentstringCard content. For text cards this is canonical raw Markdown, preserved exactly, with a maximum of 512 KiB measured in UTF-8 bytes.
fileEtagstringETag returned by the completed upload PUT. Include it when creating an uploaded-file card so Teak can verify the exact stored object.
fileKeystringfileNamestringfileSizenumbermimeTypestringnotesstring | nullpageSnapshotKeystringFrom POST /v1/page-snapshots/upload: the page as the browser showed it, gzipped, which becomes the link's saved copy instead of the page Teak fetches. Only for links; a key that isn't one of your snapshot uploads is ignored, and the card is still saved. Not allowed with fileKey.
sourcestringA free label for what saved the card, kept in its metadata. To record the page a card came from, use sourceUrl.
sourceTitlestringThe title of the page in sourceUrl. Trimmed, and cut to 300 characters. Needs sourceUrl.
sourceUrlstringThe page the card was saved from, such as the page a quote was selected on: an http or https URL of at most 2048 characters. Unlike url, it never makes the card a link, and it isn't part of the duplicate check. Not allowed with fileKey.
tagsstring[]urlstringCreated card
appUrlstring<uri>requiredcardCardShow propertiesHide properties
aiSummarystring | nullaiTagsstring[]requiredaiTranscriptstring | nullWhat is said in the card: an audio or video file's transcript, a Vimeo video's captions, or a podcast episode's transcript.
appUrlstring<uri>requiredarchiveobject | nullA link's saved copy of its page, which Teak keeps privately and opens when the original is gone: full (text, styles and images, up to 20 MB) or text_only (the page was too large), its size in bytes and when it was taken. Null until the copy is saved, and for other cards. The copy itself stays in the app.
Show propertiesHide properties
bytesnumberrequiredcapturedAtnumberrequiredkindstringrequiredfulltext_onlynullarticleobject | nullA link's article, taken from its saved copy: its length in words and minutes to read. Null for other cards, until the article is ready, and for pages that aren't articles. Read it with GET /v1/cards/{cardId}/content?kind=article.
Show propertiesHide properties
readingMinutesnumberrequiredwordCountnumberrequirednullcompactUrlstring | nullrequired256px rendition URL for small cards; present for image uploads.
contentstringrequiredhighlightCountnumberPassages highlighted in a link's article, up to 200; 0 for other cards. List them with GET /v1/cards/{cardId}/highlights.
isDeletedbooleanmetadataStatusstring | nullprocessingStatusobject | nullPer-stage processing state (classify, categorize, metadata, renderables, screenshot, archive, article), or null once nothing is tracked.
linkPreviewDescriptionstring | nulllinkFactsobject[]Show propertiesHide properties
objectlabelstringrequiredvaluestringrequiredlinkPreviewTitlestring | nulllinkCategorystring | nullWhat a link is, such as article, movie, product or game, or null before Teak has read it. A plain string: new categories are added over time, so accept values you don't know.
linkPriceobject | nullA 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 propertiesHide properties
amountnumberrequiredcurrencystring | nullrequiredlinkFaviconUrlstring | nullfileWidthnumber | nullfileHeightnumber | nullaudioWaveformobject | nullAudio 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 propertiesHide properties
detailnumber[]requiredgridnumber[]requiredvideoScrubobject | nullA 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 propertiesHide properties
frameHeightnumberrequiredframeWidthnumberrequiredframesnumberrequiredurlstringrequiredcolorsobject[]Show propertiesHide properties
objecthexstringrequirednamestringcreatedAtnumberrequireddetailUrlstring | nullfileExtensionstring | nullfileKindstring | nullfileLanguagestring | nullfileNamestring | nullfilePreviewobject | nullfileSizenumber | nullfileUrlstring | nullidstringrequiredarchivedAtnumber | nullWhen the card was archived, or null when it isn't.
completedAtnumber | nullWhen the link was marked read, watched, bought or otherwise done (POST /v1/cards/{cardId}/done), or null when it isn't. is:done and is:todo in q filter on it.
folderIdsstring[]Ids of the folders the card is in (at most 50).
isArchivedbooleanrequiredArchived cards are hidden from the library and listings unless you ask for them with archived.
isFavoritedbooleanrequiredisPinnedbooleanTrue while the card is pinned to the top of the library, at most 12 cards. Archiving or trashing a card unpins it.
isHiddenbooleanTrue 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 | nulllinkPreviewMediaobject[]Show propertiesHide properties
objecttypestringrequiredimagevideourlstringrequiredcontentTypestringwidthnumberheightnumberposterUrlstringposterContentTypestringposterWidthnumberposterHeightnumberlinkSiteNamestring | nulllinkAuthorstring | nulllinkPublisherstring | nulllinkPublishedAtstring | nullmetadataDescriptionstring | nullmetadataTitlestring | nullmimeTypestring | nullnotesstring | nullplaceholderUrlstring | nullrequired48px loading-placeholder rendition URL; present for image uploads.
savedAtnumberWhen the card was last saved. It starts equal to createdAt and moves to the time of the save when you save the same link again (POST /v1/cards answers resaved: true). sort=newest and sort=oldest order by it. createdAt stays the date the card was first saved.
screenshotUrlstring | nullsourceTitlestring | nullThe title of the page the card was saved from, beside sourceUrl.
sourceUrlstring | nullThe 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[]requiredthumbnailOverriddenbooleanTrue when linkPreviewImageUrl is an image chosen for this link (PUT /v1/cards/{cardId}/thumbnail) rather than the one Teak found.
thumbnailUrlstring | nulltypestringrequiredupdatedAtnumberrequiredurlstring | nulllinksCardLinkRef[]Cards this card links to with [[Title|teak:<id>]], in the order they appear in content, at most 100. A link to a card in Trash, a deleted card or another account's card is missing, with a null title and type. Only on single-card responses: lists and the changes feed leave it out.
Show propertiesHide properties
CardLinkRefidstringrequiredmissingbooleanrequiredTrue when the linked card is in Trash, deleted or not yours.
titlestring | nullrequiredtypestring | nullrequiredlinksTruncatedbooleanTrue when the card has more than 100 links.
backlinksCardLinkRef[]Your cards that link to this card, most recently updated first, at most 100; cards in Trash and hidden cards are left out. Only on single-card responses.
Show propertiesHide properties
CardLinkRefidstringrequiredmissingbooleanrequiredTrue when the linked card is in Trash, deleted or not yours.
titlestring | nullrequiredtypestring | nullrequiredbacklinksTruncatedbooleanTrue when more than 100 cards link to this card.
cardIdstringrequiredresavedbooleanPresent and true when the link was already in Teak: no card was made, and the card that has it moved to the top of sort=newest (its savedAt is now). cardId and card are that card. Tags, notes and content sent with the save were not applied; PATCH /v1/cards/{cardId} to add them.
truestatusstringrequiredAlways created, also for a re-save: check resaved.
createdwasArchivedbooleanPresent and true when the re-saved card was archived; it is back in the library.
true