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 → Security → API keys and create a key. Keys start with teakapi_. 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

401

Missing, invalid, expired, or revoked credential

429

Rate limit exceeded

500

Profile or authorization service unavailable

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

Request

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

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

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

import requests

response = requests.get(
    "https://teakvault.com/api/v1/me",
    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/me", 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/me")
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/me',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
  ],
]);

$response = curl_exec($curl);

Response

{
  "data": {
    "id": "string",
    "email": "user@example.com",
    "name": "string"
  }
}

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.

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

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

linkPreviewDescriptionstring | null

linkFactsobject[]

Show properties

Array of object

labelstringrequired

valuestringrequired

linkPreviewTitlestring | null

linkFaviconUrlstring | null

fileWidthnumber | null

fileHeightnumber | null

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

isFavoritedbooleanrequired

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

tagsstring[]required

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",
  "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  \"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  \"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  \"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  \"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  \"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",
  "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,
    "linkPreviewDescription": "string",
    "linkFacts": [
      {
        "label": "string",
        "value": "string"
      }
    ],
    "linkPreviewTitle": "string",
    "linkFaviconUrl": "string",
    "fileWidth": 0,
    "fileHeight": 0,
    "colors": [
      {
        "hex": "string",
        "name": "string"
      }
    ],
    "createdAt": 0,
    "detailUrl": "string",
    "fileExtension": "string",
    "fileKind": "string",
    "fileLanguage": "string",
    "fileName": "string",
    "filePreview": {},
    "fileSize": 0,
    "fileUrl": "string",
    "id": "string",
    "isFavorited": 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",
    "tags": [
      "string"
    ],
    "thumbnailUrl": "string",
    "type": "string",
    "updatedAt": 0,
    "url": "string"
  },
  "cardId": "string",
  "status": "created"
}

Next steps

API guide

Authentication, uploads, search, pagination, and errors.

API Reference

Every operation, field, and schema.

MCP

Give an AI client the same card operations.