Разработчикам · API-ключи
Справочник по API-ключам TypeHop
API-ключ позволяет ИИ-приложению или вашему коду читать диктовки, синхронизированные с вашим аккаунтом TypeHop, с любого устройства. Ключи работают только на чтение: они могут искать и читать диктовки и ваши собственные слова, но ничего не изменяют и не удаляют. Доступ идёт через один удалённый MCP-эндпоинт, поэтому такие приложения, как Claude Code, Cursor и Codex, подключаются одной строкой настройки.
Создание ключа
- Откройте приложение TypeHop для Mac и перейдите в Integrations → API keys.
- Нажмите Create API key и назовите ключ по имени приложения или компьютера, который будет его использовать, например «Cursor на моём ноутбуке».
- Сразу скопируйте ключ. 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 · -32602tools/call указал несуществующий инструмент.500 · -32603Ошибка сервера. Повторите запрос с задержкой (backoff).
Лимиты и безопасность
- Активные ключи
- До 10 на аккаунт. Отзовите один, чтобы создать другой.
- Размер запроса
- 256 КБ на запрос, до 20 сообщений в пакете.
- Результаты
- До 50 диктовок за вызов;
recent_dictationsзаглядывает назад не более чем на 365 дней. - Область доступа
- Диктовки, синхронизированные с вашим аккаунтом, и ваши собственные слова. Ничего не записывается.
- Используйте один ключ на приложение или компьютер, чтобы можно было отозвать один, не сломав остальные.
- Храните ключи на своём компьютере или бэкенде. Никогда не помещайте ключ в браузерный код, сборку мобильного приложения или публичный репозиторий.
- Если ключ утёк, отзовите его в Integrations → API keys. Он перестанет работать со следующего запроса.
Вопросы: support@typehop.com. Нужен обзор? Смотрите API TypeHop.