Highlight a passage

Finds the quote in the card’s saved article and highlights it: the first match, unless prefix or suffix points at another. A passage that overlaps a highlight merges with it, keeping the older note. A card holds up to 200 highlights, and a highlighted link keeps its saved copy and article: Refresh details and saving it again no longer replace them.

POST/v1/cards/{cardId}/highlights

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

requiredapplication/json

quotestringrequired

Text from the card's article, at most 5,000 characters. Whitespace, curly quotes, dash styles and case don't need to match.

notestring

At most 2,000 characters.

prefixstring

Text just before the quote, to pick one of its repeats. Without it, or suffix, the first match is highlighted.

suffixstring

Text just after the quote, to pick one of its repeats.

Responses

200

The passage was highlighted already, or the new highlight merged with one it overlapped

idstringrequired

cardIdstringrequired

quotestringrequired

The highlighted text.

notestring | nullrequired

anchoredbooleanrequired

False while Teak hasn't found the quote in the card's saved article: an imported highlight waiting for the article, or one the article doesn't have.

sourcestringrequired

Where it was made: in Teak's reader, through this API, or by an import. Clients should accept values they don't know.

Allowed:readerapiimport

createdAtnumberrequired

updatedAtnumberrequired

201

Highlight created

idstringrequired

cardIdstringrequired

quotestringrequired

The highlighted text.

notestring | nullrequired

anchoredbooleanrequired

False while Teak hasn't found the quote in the card's saved article: an imported highlight waiting for the article, or one the article doesn't have.

sourcestringrequired

Where it was made: in Teak's reader, through this API, or by an import. Clients should accept values they don't know.

Allowed:readerapiimport

createdAtnumberrequired

updatedAtnumberrequired

400

INVALID_INPUT: no quote, or a quote or note too long

codestringrequired

errorstringrequired

retryAtnumber | null

404

Card not found

codestringrequired

errorstringrequired

retryAtnumber | null

409

NO_ARTICLE: the card isn't a link with a saved article, or is in Trash. HIGHLIGHT_LIMIT: the card has 200 highlights. CONFLICT: the card's saved article changed while the quote was being found; try again

codestringrequired

errorstringrequired

retryAtnumber | null

422

QUOTE_NOT_FOUND: the article doesn't have the quote

codestringrequired

errorstringrequired

retryAtnumber | null

429

RATE_LIMITED

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

quotestring*Text from the card's article, at most 5,000 characters. Whitespace, curly quotes, dash styles and case don't need to match.notestringAt most 2,000 characters.prefixstringText just before the quote, to pick one of its repeats. Without it, or `suffix`, the first match is highlighted.suffixstringText just after the quote, to pick one of its repeats.

Request

curl -X POST 'https://teakvault.com/api/v1/cards/string/highlights' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "quote": "string",
  "note": "string",
  "prefix": "string",
  "suffix": "string"
}'

const response = await fetch("https://teakvault.com/api/v1/cards/string/highlights", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"quote\": \"string\",\n  \"note\": \"string\",\n  \"prefix\": \"string\",\n  \"suffix\": \"string\"\n}"
});

const response: Response = await fetch("https://teakvault.com/api/v1/cards/string/highlights", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"quote\": \"string\",\n  \"note\": \"string\",\n  \"prefix\": \"string\",\n  \"suffix\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://teakvault.com/api/v1/cards/string/highlights",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"quote\": \"string\",\n  \"note\": \"string\",\n  \"prefix\": \"string\",\n  \"suffix\": \"string\"\n}",
)

package main

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

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

$response = curl_exec($curl);

Response

{
  "id": "string",
  "cardId": "string",
  "quote": "string",
  "note": "string",
  "anchored": true,
  "source": "reader",
  "createdAt": 0,
  "updatedAt": 0
}

{
  "id": "string",
  "cardId": "string",
  "quote": "string",
  "note": "string",
  "anchored": true,
  "source": "reader",
  "createdAt": 0,
  "updatedAt": 0
}

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

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

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

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

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