Create a card

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

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

appUrlstring<uri>required

compactUrlstring | nullrequired

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

contentstringrequired

isDeletedboolean

metadataStatusstring | null

processingStatusobject | null

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

linkPreviewDescriptionstring | null

linkFactsobject[]

Show properties

Array of object

labelstringrequired

valuestringrequired

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

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.

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

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.

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

cardIdstringrequired

statusstringrequired

Allowed:created

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

Bodyapplication/json

Request body

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",
  "source": "string",
  "sourceTitle": "string",
  "sourceUrl": "https://example.com/essay",
  "tags": [
    "string"
  ],
  "url": "string"
}'

const response = await fetch("https://teakvault.com/api/v1/cards", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"cardType\": \"text\",\n  \"content\": \"  # Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n\",\n  \"fileEtag\": \"\\\"d41d8cd98f00b204e9800998ecf8427e\\\"\",\n  \"fileKey\": \"string\",\n  \"fileName\": \"string\",\n  \"fileSize\": 0,\n  \"mimeType\": \"string\",\n  \"notes\": \"string\",\n  \"source\": \"string\",\n  \"sourceTitle\": \"string\",\n  \"sourceUrl\": \"https://example.com/essay\",\n  \"tags\": [\n    \"string\"\n  ],\n  \"url\": \"string\"\n}"
});

const response: Response = await fetch("https://teakvault.com/api/v1/cards", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"cardType\": \"text\",\n  \"content\": \"  # Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n\",\n  \"fileEtag\": \"\\\"d41d8cd98f00b204e9800998ecf8427e\\\"\",\n  \"fileKey\": \"string\",\n  \"fileName\": \"string\",\n  \"fileSize\": 0,\n  \"mimeType\": \"string\",\n  \"notes\": \"string\",\n  \"source\": \"string\",\n  \"sourceTitle\": \"string\",\n  \"sourceUrl\": \"https://example.com/essay\",\n  \"tags\": [\n    \"string\"\n  ],\n  \"url\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://teakvault.com/api/v1/cards",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"cardType\": \"text\",\n  \"content\": \"  # Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n\",\n  \"fileEtag\": \"\\\"d41d8cd98f00b204e9800998ecf8427e\\\"\",\n  \"fileKey\": \"string\",\n  \"fileName\": \"string\",\n  \"fileSize\": 0,\n  \"mimeType\": \"string\",\n  \"notes\": \"string\",\n  \"source\": \"string\",\n  \"sourceTitle\": \"string\",\n  \"sourceUrl\": \"https://example.com/essay\",\n  \"tags\": [\n    \"string\"\n  ],\n  \"url\": \"string\"\n}",
)

package main

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

func main() {
	body := strings.NewReader("{\n  \"cardType\": \"text\",\n  \"content\": \"  # Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n\",\n  \"fileEtag\": \"\\\"d41d8cd98f00b204e9800998ecf8427e\\\"\",\n  \"fileKey\": \"string\",\n  \"fileName\": \"string\",\n  \"fileSize\": 0,\n  \"mimeType\": \"string\",\n  \"notes\": \"string\",\n  \"source\": \"string\",\n  \"sourceTitle\": \"string\",\n  \"sourceUrl\": \"https://example.com/essay\",\n  \"tags\": [\n    \"string\"\n  ],\n  \"url\": \"string\"\n}")
	req, err := http.NewRequest("POST", "https://teakvault.com/api/v1/cards", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "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::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = "{\n  \"cardType\": \"text\",\n  \"content\": \"  \# Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n\",\n  \"fileEtag\": \"\\\"d41d8cd98f00b204e9800998ecf8427e\\\"\",\n  \"fileKey\": \"string\",\n  \"fileName\": \"string\",\n  \"fileSize\": 0,\n  \"mimeType\": \"string\",\n  \"notes\": \"string\",\n  \"source\": \"string\",\n  \"sourceTitle\": \"string\",\n  \"sourceUrl\": \"https://example.com/essay\",\n  \"tags\": [\n    \"string\"\n  ],\n  \"url\": \"string\"\n}"

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 => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "cardType": "text",
  "content": "  # Draft\\r\\n\\r\\n- [ ] Keep spacing  \\n",
  "fileEtag": "\\"d41d8cd98f00b204e9800998ecf8427e\\"",
  "fileKey": "string",
  "fileName": "string",
  "fileSize": 0,
  "mimeType": "string",
  "notes": "string",
  "source": "string",
  "sourceTitle": "string",
  "sourceUrl": "https://example.com/essay",
  "tags": [
    "string"
  ],
  "url": "string"
}',
]);

$response = curl_exec($curl);

Response

{
  "appUrl": "http://example.com",
  "card": {
    "aiSummary": "string",
    "aiTags": [
      "string"
    ],
    "aiTranscript": "string",
    "appUrl": "http://example.com",
    "compactUrl": "string",
    "content": "string",
    "isDeleted": true,
    "metadataStatus": "string",
    "processingStatus": {},
    "linkPreviewDescription": "string",
    "linkFacts": [
      {
        "label": "string",
        "value": "string"
      }
    ],
    "linkPreviewTitle": "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,
    "folderIds": [
      "string"
    ],
    "isArchived": true,
    "isFavorited": 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",
    "screenshotUrl": "string",
    "sourceTitle": "string",
    "sourceUrl": "string",
    "tags": [
      "string"
    ],
    "thumbnailOverridden": true,
    "thumbnailUrl": "string",
    "type": "string",
    "updatedAt": 0,
    "url": "string"
  },
  "cardId": "string",
  "status": "created"
}