TypeHop
Скачать

Разработчикам · API-ключи

Справочник по API-ключам TypeHop

API-ключ позволяет ИИ-приложению или вашему коду читать диктовки, синхронизированные с вашим аккаунтом TypeHop, с любого устройства. Ключи работают только на чтение: они могут искать и читать диктовки и ваши собственные слова, но ничего не изменяют и не удаляют. Доступ идёт через один удалённый MCP-эндпоинт, поэтому такие приложения, как Claude Code, Cursor и Codex, подключаются одной строкой настройки.

Создание ключа

  1. Откройте приложение TypeHop для Mac и перейдите в Integrations → API keys.
  2. Нажмите Create API key и назовите ключ по имени приложения или компьютера, который будет его использовать, например «Cursor на моём ноутбуке».
  3. Сразу скопируйте ключ. TypeHop хранит только его хеш, поэтому полный ключ показывается один раз. Потеряли? Создайте новый и отзовите старый.

Ключи начинаются с thp_mcp_. В списке в приложении для каждого ключа показаны его первые символы, дата создания и дата последнего использования. Отзыв ключа немедленно останавливает все приложения, которые его используют.

Аутентификация

Передавайте ключ как Bearer-токен в каждом запросе. OAuth-потока и сессии, которую нужно открывать, нет.

Эндпоинт
https://api.typehop.com/v1/mcp
Метод
Только POST. GET и DELETE возвращают 405.
Заголовок
Authorization: Bearer thp_mcp_YOUR_KEY
Тело
JSON-RPC 2.0, Content-Type: application/json

Ключ отсутствует или отозван

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="typehop-mcp"

{ "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "This token is invalid or was revoked." } }

Подключение ИИ-приложения

Большинство людей никогда не вызывают эндпоинт вручную. Приложение для Mac показывает точную настройку для Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed и Claude Desktop в разделе Connect an app, с уже подставленным новым ключом. Те же сниппеты есть на странице MCP. Например, для Claude Code:

claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"

Любой другой клиент, поддерживающий удалённые MCP-серверы по Streamable HTTP, работает с URL эндпоинта и заголовком выше. Для кастомных коннекторов Claude.ai и ChatGPT нужен OAuth, который TypeHop пока не поддерживает.

Вызов из кода

Эндпоинт работает по Model Context Protocol: сообщения JSON-RPC 2.0 в POST-запросе и один JSON-ответ. Он не хранит состояние, поэтому заголовков сессии и server-sent events нет. Поддерживаемые версии протокола: 2025-06-18, 2025-03-26, 2024-11-05.

1. Инициализация (необязательно, но MCP-клиенты её выполняют)

curl https://api.typehop.com/v1/mcp \
  -H "Authorization: Bearer thp_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'

2. Получение списка инструментов

curl https://api.typehop.com/v1/mcp \
  -H "Authorization: Bearer thp_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. Вызов инструмента

curl https://api.typehop.com/v1/mcp \
  -H "Authorization: Bearer thp_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_dictations","arguments":{"query":"launch plan","limit":5}}}'

Ответ · 200

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[2026-11-03T09:14:22.000Z · Slack · id 3f6c1a2e-8b1d-4c55-9a0e-6b2f7d1e4c90]\nThe launch plan moves to next Tuesday..."
      }
    ],
    "isError": false
  }
}

Каждая диктовка в результате начинается со строки заголовка: [created at · app · id <id>], затем идёт очищенный текст. Передайте этот id в get_dictation, чтобы получить исходный транскрипт. Также можно отправить в одном запросе массив до 20 сообщений; на уведомления (сообщения без id) приходит 202 без тела. Поддерживается ping.

Инструменты

Все инструменты работают только на чтение и возвращают обычный текст в result.content[0].text.

search_dictations · Поиск диктовок

Полнотекстовый поиск по всему, что продиктовал пользователь. Сначала возвращает самые новые совпадения.

  • query (string, обязательно): Слова или фраза для поиска.
  • limit (integer 1–50, по умолчанию 20)

recent_dictations · Недавние диктовки

Последние диктовки пользователя, при желании только за последние несколько дней.

  • limit (integer 1–50, по умолчанию 20)
  • days (integer 1–365): Только диктовки за последние N дней.

get_dictation · Получить диктовку

Одна диктовка по id: очищенный текст и исходный транскрипт.

  • id (string, обязательно): Идентификатор из результатов поиска или списка недавних.

list_dictionary · Собственные слова

Собственные слова и написания пользователя (имена, жаргон).

Без аргументов.

Если инструмент не может ответить (пустой запрос, неизвестный id, временный сбой чтения), ответом всё равно будет результат 200 с isError: true и предложением, которое сможет прочитать модель.

Ошибки

Ошибки протокола возвращаются как объект JSON-RPC error: { "code": <number>, "message": "<text>" }.

  • 401 · -32001 Заголовок Authorization отсутствует, либо ключ недействителен или отозван.
  • 400 · -32700 Тело не является корректным JSON.
  • 413 · -32600 Тело больше 256 КБ.
  • 200 · -32600 Сообщение не соответствует JSON-RPC 2.0 (нет "jsonrpc": "2.0" или "method").
  • 200 · -32601 Неизвестный метод.
  • 200 · -32602 tools/call указал несуществующий инструмент.
  • 500 · -32603 Ошибка сервера. Повторите запрос с задержкой (backoff).

Лимиты и безопасность

Активные ключи
До 10 на аккаунт. Отзовите один, чтобы создать другой.
Размер запроса
256 КБ на запрос, до 20 сообщений в пакете.
Результаты
До 50 диктовок за вызов; recent_dictations заглядывает назад не более чем на 365 дней.
Область доступа
Диктовки, синхронизированные с вашим аккаунтом, и ваши собственные слова. Ничего не записывается.
  • Используйте один ключ на приложение или компьютер, чтобы можно было отозвать один, не сломав остальные.
  • Храните ключи на своём компьютере или бэкенде. Никогда не помещайте ключ в браузерный код, сборку мобильного приложения или публичный репозиторий.
  • Если ключ утёк, отзовите его в Integrations → API keys. Он перестанет работать со следующего запроса.

Вопросы: support@typehop.com. Нужен обзор? Смотрите API TypeHop.

Other products from us:SmashSend·TidySupport·SuperBuilder·Inbounter·Blossu·KnowledgeSDK