Skip to main content

​
Introduction

The Teak API allows you to programmatically interact with your personal knowledge hub. You can create cards, search your collection, and manage favorites using simple HTTP requests.
The Teak API is currently designed for integration with tools like Raycast. More endpoints will be added in future releases.

​
Base URL

All API requests should be made to your Convex deployment URL: 
https://[your-deployment].convex.cloud
You can find your deployment URL in the Convex dashboard for your Teak instance.

​
API Endpoints

The following endpoints are available:
EndpointMethodDescription
/api/raycast/quick-savePOSTCreate a new card (text or link)
/api/raycast/searchGETSearch all cards
/api/raycast/favoritesGETSearch favorited cards

​
Request Format

All requests must include:
  1. Authentication header: Bearer token with your API key
  2. Content-Type header: application/json for POST requests
  3. Proper request body: JSON-formatted data for POST requests

​
Example Request

curl -X POST https://[your-deployment].convex.cloud/api/raycast/quick-save \
  -H "Authorization: Bearer teakapi_[your-api-key]" \
  -H "Content-Type: application/json" \
  -d '{"content": "https://example.com"}'

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes:
  • 200: Success
  • 400: Bad request (invalid input)
  • 401: Unauthorized (missing or invalid API key)
  • 405: Method not allowed
  • 429: Rate limited (too many requests)
  • 500: Internal server error

​
Success Response

{
  "status": "created",
  "cardId": "jh7x5t9p2k8n4m1q6r3s"
}

​
Error Response

{
  "code": "INVALID_INPUT",
  "error": "Field `content` must be a non-empty string"
}

​
Rate Limits

API requests are rate limited to 120 requests per minute per API key.
When you exceed the rate limit, you’ll receive a 429 status code with a response like: 
{
  "code": "RATE_LIMITED",
  "error": "Too many requests",
  "retryAt": 1704067200000
}
The retryAt field contains a Unix timestamp (in milliseconds) indicating when you can retry your request.

​
Error Codes

CodeDescription
BAD_REQUESTThe request was malformed or missing required fields
INVALID_INPUTThe input data failed validation
UNAUTHORIZEDMissing or invalid Authorization header
INVALID_API_KEYThe API key is invalid or has been revoked
RATE_LIMITEDToo many requests - retry after the specified time
METHOD_NOT_ALLOWEDThe HTTP method is not supported for this endpoint
INTERNAL_ERRORAn unexpected server error occurred
All timestamps in the API use Unix time in milliseconds.

​
Next Steps

Authentication

Learn how to generate and use API keys

Create Card

Create cards via the API

Build docs developers (and LLMs) love

Get started for freeTalk to us