Skip to content

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

Settings → Integrations with Save by email, apps and extensions, and 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.

GET/v1/me
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.

Responses
200

Permanent Teak owner ID and current profile

dataobjectrequired
Show properties
idstringrequired

Permanent Teak owner ID

emailstring<email>required
namestring
cardCountnumber

Cards outside Trash

cardLimitnumber | null

Free plan card limit; null on Pro

planstring
Allowed:freepro
localestringrequired

The 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

401

Missing, invalid, expired, or revoked credential

429

Rate limit exceeded

500

Profile or authorization service unavailable

Try it
Server
Authorization
Request
curl -X GET 'https://teakvault.com/api/v1/me' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "data": {
    "id": "string",
    "email": "user@example.com",
    "name": "string",
    "cardCount": 0,
    "cardLimit": 0,
    "plan": "free",
    "locale": "string",
    "settingsUrl": "http://example.com"
  }
}

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.

POST/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.

Request body
application/json
cardTypestring

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

Allowed:textlinkimagevideoaudiodocumentpalettequote
contentstring

Card content. For text cards this is canonical raw Markdown, preserved exactly, with a maximum of 512 KiB measured in UTF-8 bytes.

fileEtagstring

ETag returned by the completed upload PUT. Include it when creating an uploaded-file card so Teak can verify the exact stored object.

fileKeystring
fileNamestring
fileSizenumber
mimeTypestring
notesstring | null
pageSnapshotKeystring

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

sourcestring

A free label for what saved the card, kept in its metadata. To record the page a card came from, use sourceUrl.

sourceTitlestring

The title of the page in sourceUrl. Trimmed, and cut to 300 characters. Needs sourceUrl.

sourceUrlstring

The 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[]
urlstring
Responses
200

Created card

appUrlstring<uri>required
cardCard
Show properties
aiSummarystring | null
aiTagsstring[]required
aiTranscriptstring | null

What 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>required
archiveobject | null

A 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 properties
One of:
object
bytesnumberrequired
capturedAtnumberrequired
kindstringrequired
Allowed:fulltext_only
null
null
articleobject | null

A 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 properties
One of:
object
readingMinutesnumberrequired
wordCountnumberrequired
null
null
compactUrlstring | nullrequired

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

contentstringrequired
highlightCountnumber

Passages highlighted in a link's article, up to 200; 0 for other cards. List them with GET /v1/cards/{cardId}/highlights.

isDeletedboolean
metadataStatusstring | null
processingStatusobject | null

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

linkPreviewDescriptionstring | null
linkFactsobject[]
Show properties
Array of object
labelstringrequired
valuestringrequired
linkPreviewTitlestring | null
linkCategorystring | null

What 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 | 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
linkFaviconUrlstring | null
fileWidthnumber | null
fileHeightnumber | 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
colorsobject[]
Show properties
Array of object
hexstringrequired
namestring
createdAtnumberrequired
detailUrlstring | null
fileExtensionstring | null
fileKindstring | null
fileLanguagestring | null
fileNamestring | null
filePreviewobject | null
fileSizenumber | null
fileUrlstring | null
idstringrequired
archivedAtnumber | null

When the card was archived, or null when it isn't.

completedAtnumber | null

When 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).

isArchivedbooleanrequired

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

isFavoritedbooleanrequired
isPinnedboolean

True while the card is pinned to the top of the library, at most 12 cards. Archiving or trashing a card unpins it.

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
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
mimeTypestring | null
notesstring | null
placeholderUrlstring | nullrequired

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

savedAtnumber

When 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 | 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
linksCardLinkRef[]

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 properties
Array of CardLinkRef
idstringrequired
missingbooleanrequired

True when the linked card is in Trash, deleted or not yours.

titlestring | nullrequired
typestring | nullrequired
linksTruncatedboolean

True 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 properties
Array of CardLinkRef
idstringrequired
missingbooleanrequired

True when the linked card is in Trash, deleted or not yours.

titlestring | nullrequired
typestring | nullrequired
backlinksTruncatedboolean

True when more than 100 cards link to this card.

cardIdstringrequired
resavedboolean

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

Allowed:true
statusstringrequired

Always created, also for a re-save: check resaved.

Allowed:created
wasArchivedboolean

Present and true when the re-saved card was archived; it is back in the library.

Allowed:true
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST 'https://teakvault.com/api/v1/cards' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "cardType": "text",
  "content": "  # Draft\r\n\r\n- [ ] Keep spacing  \n",
  "fileEtag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "fileKey": "string",
  "fileName": "string",
  "fileSize": 0,
  "mimeType": "string",
  "notes": "string",
  "pageSnapshotKey": "string",
  "source": "string",
  "sourceTitle": "string",
  "sourceUrl": "https://example.com/essay",
  "tags": [
    "string"
  ],
  "url": "string"
}'
Response
{
  "appUrl": "http://example.com",
  "card": {
    "aiSummary": "string",
    "aiTags": [
      "string"
    ],
    "aiTranscript": "string",
    "appUrl": "http://example.com",
    "archive": {
      "bytes": 0,
      "capturedAt": 0,
      "kind": "full"
    },
    "article": {
      "readingMinutes": 0,
      "wordCount": 0
    },
    "compactUrl": "string",
    "content": "string",
    "highlightCount": 0,
    "isDeleted": true,
    "metadataStatus": "string",
    "processingStatus": {},
    "linkPreviewDescription": "string",
    "linkFacts": [
      {
        "label": "string",
        "value": "string"
      }
    ],
    "linkPreviewTitle": "string",
    "linkCategory": "string",
    "linkPrice": {
      "amount": 0,
      "currency": "string"
    },
    "linkFaviconUrl": "string",
    "fileWidth": 0,
    "fileHeight": 0,
    "audioWaveform": {
      "detail": [
        0
      ],
      "grid": [
        0
      ]
    },
    "videoScrub": {
      "frameHeight": 0,
      "frameWidth": 0,
      "frames": 0,
      "url": "string"
    },
    "colors": [
      {
        "hex": "string",
        "name": "string"
      }
    ],
    "createdAt": 0,
    "detailUrl": "string",
    "fileExtension": "string",
    "fileKind": "string",
    "fileLanguage": "string",
    "fileName": "string",
    "filePreview": {},
    "fileSize": 0,
    "fileUrl": "string",
    "id": "string",
    "archivedAt": 0,
    "completedAt": 0,
    "folderIds": [
      "string"
    ],
    "isArchived": true,
    "isFavorited": true,
    "isPinned": true,
    "isHidden": true,
    "linkPreviewImageUrl": "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",
    "mimeType": "string",
    "notes": "string",
    "placeholderUrl": "string",
    "savedAt": 0,
    "screenshotUrl": "string",
    "sourceTitle": "string",
    "sourceUrl": "string",
    "tags": [
      "string"
    ],
    "thumbnailOverridden": true,
    "thumbnailUrl": "string",
    "type": "string",
    "updatedAt": 0,
    "url": "string",
    "links": [
      {
        "id": "string",
        "missing": true,
        "title": "string",
        "type": "string"
      }
    ],
    "linksTruncated": true,
    "backlinks": [
      {
        "id": "string",
        "missing": true,
        "title": "string",
        "type": "string"
      }
    ],
    "backlinksTruncated": true
  },
  "cardId": "string",
  "resaved": true,
  "status": "created",
  "wasArchived": true
}

Next steps

Last updated on

Was this page helpful?