---
title: API Quickstart
description: 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
mode: wide
sidebar:
  badge: "New"
---

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:

```bash
export TEAK_API_KEY=teakapi_...
```

:::warning[Keep secrets out of logs]
Never commit `teakapi_` keys or paste them into public issue trackers. Rotate a key immediately if it leaks.
:::

## 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`

**Responses**

- `200` — Permanent Teak owner ID and current profile
- `401` — Missing, invalid, expired, or revoked credential
- `429` — Rate limit exceeded
- `500` — Profile or authorization service unavailable

Response example, 200:

```json
{
  "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`

**Request body** (`application/json`)

- `cardType` (string) — 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.
- `content` (string) — Card content. For text cards this is canonical raw Markdown, preserved exactly, with a maximum of 512 KiB measured in UTF-8 bytes.
- `fileEtag` (string) — ETag returned by the completed upload PUT. Include it when creating an uploaded-file card so Teak can verify the exact stored object.
- `fileKey` (string)
- `fileName` (string)
- `fileSize` (number)
- `mimeType` (string)
- `notes` (string | null)
- `source` (string)
- `tags` (string[])
- `url` (string)

Request body example:

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

**Responses**

- `200` — Created card

Response example, 200:

```json
{
  "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](/docs/api)**

Authentication, uploads, search, pagination, and errors.

**[API Reference](/reference)**

Every operation, field, and schema.

**[MCP](/docs/mcp)**

Give an AI client the same card operations.