Pin or unpin a card

Pins a card to the top of the library, or unpins it. A new pin goes first. Up to 12 cards can be pinned, and archiving or trashing a card unpins it.

PATCH/v1/cards/{cardId}/pin

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.

Path parameters

cardIdstringrequired

Request body

application/json

isPinnedbooleanrequired

Responses

200

The card with its new isPinned. Pinning a pinned card, or unpinning one that isn't, changes nothing

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.

400

PIN_LIMIT_REACHED: 12 cards are already pinned; unpin one first

codestringrequired

errorstringrequired

retryAtnumber | null

404

Card not found

codestringrequired

errorstringrequired

retryAtnumber | null

409

CONFLICT: the card is archived; archived cards can't be pinned

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

cardIdpath*

Bodyapplication/json

isPinnedboolean*

Request

curl -X PATCH 'https://teakvault.com/api/v1/cards/string/pin' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "isPinned": true
}'

const response = await fetch("https://teakvault.com/api/v1/cards/string/pin", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"isPinned\": true\n}"
});

const response: Response = await fetch("https://teakvault.com/api/v1/cards/string/pin", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"isPinned\": true\n}"
});

import requests

response = requests.patch(
    "https://teakvault.com/api/v1/cards/string/pin",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"isPinned\": true\n}",
)

package main

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

func main() {
	body := strings.NewReader("{\n  \"isPinned\": true\n}")
	req, err := http.NewRequest("PATCH", "https://teakvault.com/api/v1/cards/string/pin", 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/string/pin")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = "{\n  \"isPinned\": true\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/string/pin',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{
  "isPinned": true
}',
]);

$response = curl_exec($curl);

Response

{
  "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
}

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

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

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