> ## Documentation Index
> Fetch the complete documentation index at: https://manager.harmix.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Огляд API для розробників
> REST endpoints для керування ключами Memory MCP, readiness, аналітики використання та історії запитів.
Developer API підтримує сторінки Memory MCP у застосунку PAM ([Setup](https://pam.harmix.ai/setup), [Access](https://pam.harmix.ai/access-management), [Usage](https://pam.harmix.ai/usage), [Request Log](https://pam.harmix.ai/request-log)). Використовуйте його для програмного керування Memory MCP, перевірки readiness та перегляду історії retrieval.
Ці endpoints — **не** протокол Memory MCP. Для retrieval агентом використовуйте `POST /v1/mcp/memory` — див. [Довідник MCP](/docs/uk/mcp-reference).
## Автентифікація
Developer API endpoints потребують **PAM access JWT** у заголовку `Authorization`:
```
Authorization: Bearer
```
Це відрізняється від автентифікації Memory MCP, яка підтримує **обидва** варіанти:
| Тип auth | Для чого | Формат заголовка |
| ------------ | ---------------------------------------------- | --------------------------------------------- |
| `pam_mkey` | Memory MCP (`/v1/mcp/memory`) — desktop/скрипт | `Authorization: pam_mkey_` |
| OAuth Bearer | Memory MCP (`/v1/mcp/memory`) — браузерні LLM | `Authorization: Bearer ` |
| Access JWT | Developer API (`/v1/dev/*`) | `Authorization: Bearer ` |
Браузерні клієнти знаходять OAuth через:
* `GET /.well-known/oauth-protected-resource`
* `GET /.well-known/oauth-authorization-server`
* `POST /v1/oauth/register` (DCR)
Довірені redirect URI: `https://claude.ai/api/mcp/auth_callback` та `https://chatgpt.com/connector/oauth/{id}`.
## Base URL
```
https://api.pam.harmix.ai
```
## Endpoints
| Метод | Шлях | Призначення |
| ------ | -------------------------------------------------- | ----------------------------------------------------- |
| `GET` | `/v1/dev/readiness` | Статус readiness пам'яті для чеклиста налаштування |
| `GET` | `/v1/dev/mcp-config` | MCP URL, префікс ключа, квота, приклад конфігу Claude |
| `GET` | `/v1/dev/mcp-usage-stats` | Аналітика використання (1–90 днів) |
| `GET` | `/v1/dev/mcp-requests` | Пагінована історія запитів |
| `GET` | `/v1/dev/mcp-requests/{request_id}` | Деталі одного запиту |
| `POST` | `/v1/dev/rotate-key` | Видати новий ключ, відкликати старий |
| `POST` | `/v1/dev/revoke-key` | Відкликати активний ключ |
| `GET` | `/v1/dev/oauth-connections` | Список браузерних OAuth-підключень |
| `POST` | `/v1/dev/oauth-connections/{connection_id}/revoke` | Відкликати браузерне підключення |
## Не враховуються в MCP-квотах
REST-виклики Developer API не зараховуються в ліміти Memory MCP retrieval. Лімітується лише `tools/call` → `retrieve_memory` на `/v1/mcp/memory`.
## Типові сценарії
Викличте `GET /v1/dev/readiness` і переконайтеся, що `ready: true`, перш ніж тестувати `retrieve_memory` з MCP-клієнта.
Викличте `GET /v1/dev/mcp-config`, коли потрібні account-specific деталі підключення MCP в одній відповіді. Див. [поля mcp-config](#поля-mcp-config) нижче — більшості інтеграцій достатньо підмножини полів.
Викличте `POST /v1/dev/rotate-key` із access JWT. Одразу скопіюйте новий `api_key` і оновіть конфігурацію MCP-клієнта.
Викличте `GET /v1/dev/mcp-requests` для списку останніх викликів, потім `GET /v1/dev/mcp-requests/{request_id}` для повного prompt і відповіді.
`GET /v1/dev/oauth-connections` — сесії ChatGPT і Claude web (один рядок на сім'ю refresh token). Відкликання: `POST /v1/dev/oauth-connections/{connection_id}/revoke` — те саме, що **Connected apps** у PAM.
## Поля mcp-config
`GET /v1/dev/mcp-config` — **агрегат для dashboard** Memory MCP: один poll для UI. Зовнішня автоматизація теж може його використовувати, але зазвичай не потрібні всі поля.
`api_key` майже завжди `null`. Повний секрет повертається лише один раз з `POST /v1/dev/rotate-key`. Використовуйте `key_prefix` разом із збереженим секретом або зробіть rotate і одразу скопіюйте новий ключ.
### Для налаштування MCP
| Поле | Навіщо |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `mcp_url` | Endpoint Memory MCP для вашого середовища |
| `mcp_server_name` | Id сервера (`pam_memory_mcp`) — довідково |
| `key_prefix` | Ідентифікує активний ключ агента (`pam_mkey_`) |
| `claude_code_config_example` | Готовий блок для MCP-клієнта; placeholder, якщо `api_key` — `null` |
| `oauth_registration_url` | DCR endpoint (`POST /v1/oauth/register`) |
| `oauth_authorization_url` | OAuth authorize |
| `oauth_token_url` | Token endpoint (`authorization_code`, `refresh_token`) |
| `oauth_revocation_url` | Відкликання токена |
| `oauth_protected_resource_metadata_url` | RFC 9728 metadata |
| `oauth_authorization_server_metadata_url` | Metadata authorization server |
| `oauth_client_id` | Опційний pre-issued client ID (браузер зазвичай лише MCP URL + DCR) |
| `browser_mcp_setup_instructions` | Короткі підказки для UI Memory MCP |
| `mcp_verified` | `true` після хоча б одного успішного `retrieve_memory` |
Типовий flow: poll, поки `readiness.ready` — `true` → вставте `claude_code_config_example` → додайте ключ → запустіть `hello_world_prompt` → перевірте `mcp_verified`.
### Опційні convenience-копії
| Поле | Примітки |
| ----------------------- | --------------------------------------------------------------- |
| `system_prompt_snippet` | Той самий текст, що в [Швидкому старті](/docs/uk/quickstart), крок 3 |
| `hello_world_prompt` | Рекомендований перший тестовий prompt після підключення MCP |
Можна захардкодити з документації замість читання з API.
### Також у відповіді (для polling краще окремі endpoints)
| Поле | Краще замість цього |
| ----------- | ------------------------------------------------------------------------------------------ |
| `readiness` | `GET /v1/dev/readiness` — легший, якщо потрібен лише статус pipeline |
| `quota` | Залишайте в `mcp-config` для швидкого badge, або `GET /v1/dev/mcp-usage-stats` для трендів |
### Можна ігнорувати в коді
| Поле | Примітки |
| ---------------------- | ------------------------------------------------------- |
| `developer_api_notice` | Людиночитаний вказівник на інші `/v1/dev/*` |
| `api_key` коли `null` | Очікувано — секрети через `rotate-key`, не цей endpoint |
### Приклад відповіді (скорочено)
```json theme={null}
{
"mcp_url": "https://api.pam.harmix.ai/v1/mcp/memory",
"mcp_server_name": "pam_memory_mcp",
"api_key": null,
"key_prefix": "pam_mkey_a3f8c21b",
"mcp_verified": true,
"system_prompt_snippet": "You have access to PAM Memory through the retrieve_memory MCP tool. Use it when a request may depend on company-specific context: people, projects, decisions, processes, priorities, history, customers, documents, meetings, or internal terminology. Prefer retrieving memory before making assumptions. If retrieved context is partial or uncertain, say so and ask a focused follow-up.",
"hello_world_prompt": "Summarize what you know about our company's current priorities and recent key projects based on retrieved memory.",
"claude_code_config_example": {
"mcpServers": {
"pam_memory": {
"type": "http",
"url": "https://api.pam.harmix.ai/v1/mcp/memory",
"headers": {
"Authorization": "pam_mkey_"
}
}
}
},
"readiness": {
"ready": true,
"state": "ready_rich",
"connected_sources_count": 4,
"completed_sources_count": 4,
"latest_pipeline_status": "completed",
"estimated_wait_message": null,
"has_facts": true,
"has_context_markdown": true,
"has_tree_index": true
},
"quota": {
"plan": "paid",
"status": "ok",
"requests_this_week": 28,
"weekly_limit": 300,
"remaining_this_week": 272,
"requests_this_month": 187,
"monthly_limit": 1000,
"remaining_this_month": 813,
"usage_percent": 19,
"week_reset_at": "2026-06-02T00:00:00+00:00",
"month_reset_at": "2026-06-01T00:00:00+00:00"
},
"developer_api_notice": "You also have access to developer APIs under /v1/dev (readiness, mcp-config, mcp-requests, mcp-usage-stats, rotate-key, revoke-key, oauth-connections)."
}
```
Повна схема: OpenAPI **`DeveloperMcpConfigResponse`** у Developer API reference.
## Приклади відповідей
Усі приклади використовують вигадані дані акаунта. Часові мітки — ISO 8601 UTC.
### `GET /v1/dev/readiness`
```json theme={null}
{
"ready": true,
"state": "ready_rich",
"connected_sources_count": 4,
"completed_sources_count": 4,
"latest_pipeline_status": "completed",
"estimated_wait_message": null,
"has_facts": true,
"has_context_markdown": true,
"has_tree_index": true
}
```
Під час синхронізації джерел `ready` — `false`, а `estimated_wait_message` пояснює очікування:
```json theme={null}
{
"ready": false,
"state": "processing",
"connected_sources_count": 2,
"completed_sources_count": 0,
"latest_pipeline_status": "running",
"estimated_wait_message": "Sources are connected but initial sync has not finished yet.",
"has_facts": false,
"has_context_markdown": false,
"has_tree_index": false
}
```
### `POST /v1/dev/rotate-key`
Повний `api_key` повертається **один раз**. Збережіть його одразу — наступні `GET /v1/dev/mcp-config` повертають `api_key: null`.
```json theme={null}
{
"api_key": "pam_mkey_Kx7vP2mNqR8sT4wY9zAbCdEfGhIjKlMnOp",
"key_prefix": "pam_mkey_a3f8c21b",
"rotated_at": "2026-05-29T14:22:08.451234+00:00"
}
```
### `POST /v1/dev/revoke-key`
```json theme={null}
{
"revoked": true
}
```
### `GET /v1/dev/oauth-connections`
Один елемент списку на сім'ю refresh token. `expires_at` — термін refresh token, якщо є.
```json theme={null}
{
"items": [
{
"id": 42,
"client_id": "pam_oauth_7f3a2b1c",
"client_name": "ChatGPT",
"scope": "memory:read",
"created_at": "2026-06-01T10:15:00+00:00",
"expires_at": "2026-07-01T10:15:00+00:00",
"last_used_at": "2026-06-03T08:22:11+00:00",
"revoked_at": null,
"status": "active"
}
]
}
```
`status`: `active`, `expired` або `revoked`.
### `POST /v1/dev/oauth-connections/{connection_id}/revoke`
```json theme={null}
{
"revoked": true,
"id": 42
}
```
### `GET /v1/dev/mcp-usage-stats?days=30`
Щоденна серія містить кожен календарний день у діапазоні (нулі, якщо активності не було). У `hourly_heatmap` поле `weekday`: 0 = неділя, 6 = субота.
```json theme={null}
{
"range": {
"days": 30,
"start_date": "2026-04-30",
"end_date": "2026-05-29"
},
"summary": {
"total_calls": 47,
"successful_calls": 41,
"error_calls": 6,
"success_rate": 87,
"average_duration_ms": 36240,
"estimated_tokens": 284600,
"gemini_calls_estimate": 118,
"retrieved_items_count": 312,
"triage_only_calls": 9,
"full_retrieval_calls": 32,
"last_called_at": "2026-05-29T11:47:33.128000+00:00"
},
"daily": [
{
"date": "2026-05-27",
"total_calls": 0,
"successful_calls": 0,
"tool_error_calls": 0,
"quota_exceeded_calls": 0,
"entitlement_blocked_calls": 0,
"triage_only_calls": 0,
"full_retrieval_calls": 0,
"estimated_tokens": 0,
"average_duration_ms": 0
},
{
"date": "2026-05-28",
"total_calls": 6,
"successful_calls": 5,
"tool_error_calls": 1,
"quota_exceeded_calls": 0,
"entitlement_blocked_calls": 0,
"triage_only_calls": 2,
"full_retrieval_calls": 3,
"estimated_tokens": 41800,
"average_duration_ms": 29100
},
{
"date": "2026-05-29",
"total_calls": 3,
"successful_calls": 3,
"tool_error_calls": 0,
"quota_exceeded_calls": 0,
"entitlement_blocked_calls": 0,
"triage_only_calls": 1,
"full_retrieval_calls": 2,
"estimated_tokens": 22400,
"average_duration_ms": 38420
}
],
"hourly_heatmap": [
{ "weekday": 1, "hour": 9, "total_calls": 4 },
{ "weekday": 1, "hour": 14, "total_calls": 7 },
{ "weekday": 3, "hour": 11, "total_calls": 5 }
],
"status_breakdown": [
{ "status": "success", "count": 41 },
{ "status": "tool_error", "count": 4 },
{ "status": "quota_exceeded", "count": 2 }
]
}
```
### `GET /v1/dev/mcp-requests?limit=10&page=1`
`response_json` — збережений результат MCP tool, той самий формат, що й у live `tools/call` (`content`, `structuredContent`, `isError`). Текстові поля в прикладі можуть бути скорочені.
```json theme={null}
{
"items": [
{
"request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
"tool_name": "retrieve_memory",
"prompt": "Who owns the Meridian platform rollout and what blockers were flagged in the last week?",
"response_content_text": "# Retrieved Company Context\n\n**Query:** Who owns the Meridian platform rollout...\n\n**Summary:** The rollout is owned by the Platform Engineering group. Two blockers were flagged last week: delayed vendor sign-off and a staging environment capacity issue.\n\n---\n*Retrieved 9 items | Avg relevance: 91% | Coverage: comprehensive*",
"response_json": {
"content": [
{
"type": "text",
"text": "# Retrieved Company Context\n\n**Query:** Who owns the Meridian platform rollout..."
}
],
"structuredContent": {
"status": "ok",
"memory_ready": true,
"readiness_state": "ready_rich",
"content_text": "# Retrieved Company Context\n\n...",
"triage": {
"decision": "retrieve",
"reasoning": "The query depends on project ownership and recent status from company memory.",
"rewritten_query": "Who owns the Meridian platform rollout and what blockers were flagged in the last week?"
},
"retrieval": {
"context_summary": "Meridian rollout is owned by Platform Engineering; two recent blockers involve vendor sign-off and staging capacity.",
"facts": [
{
"statement": "Platform Engineering owns the Meridian platform rollout through Q3.",
"relevance_score": 0.94,
"source_path": "company_context/projects/meridian_platform_rollout.md"
}
],
"total_items": 9,
"avg_relevance_score": 0.91,
"coverage_assessment": "comprehensive"
},
"diagnostics": {
"request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
"duration_ms": 38420,
"estimated_tokens": 6200,
"sections_searched": [
"Company Context > Projects > Meridian Platform Rollout",
"Company Context > Operations > Weekly Status"
],
"avg_relevance_score": 0.91,
"gemini_calls_estimate": 3
}
},
"isError": false
},
"duration_ms": 38420,
"created_at": "2026-05-29T11:47:33.128000+00:00"
},
{
"request_id": "8c1d4e2a-7b90-4f3c-9a1e-6d5c8b0f2e44",
"tool_name": "retrieve_memory",
"prompt": "What is our refund policy for enterprise customers?",
"response_content_text": "Monthly retrieve_memory quota exceeded. Retry after 2026-06-02T00:00:00+00:00.",
"response_json": {
"content": [
{
"type": "text",
"text": "Monthly retrieve_memory quota exceeded. Retry after 2026-06-02T00:00:00+00:00."
}
],
"structuredContent": {
"status": "error",
"error_code": "quota_exceeded",
"error_message": "Monthly retrieve_memory quota exceeded. Retry after 2026-06-02T00:00:00+00:00."
},
"isError": true
},
"duration_ms": 12,
"created_at": "2026-05-28T16:03:11.904000+00:00"
}
],
"next_cursor": "2026-05-28T16:03:11.904000+00:00|1842",
"page_size": 10,
"total_count": 47,
"current_page": 1,
"total_pages": 5
}
```
### `GET /v1/dev/mcp-requests/{request_id}`
Ті самі поля, що й у елементі списку — використовуйте, коли вже є `request_id` і потрібен повний збережений prompt і відповідь.
```json theme={null}
{
"request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
"tool_name": "retrieve_memory",
"prompt": "Who owns the Meridian platform rollout and what blockers were flagged in the last week?",
"response_content_text": "# Retrieved Company Context\n\n**Query:** Who owns the Meridian platform rollout...",
"response_json": {
"content": [{ "type": "text", "text": "# Retrieved Company Context\n\n..." }],
"structuredContent": {
"status": "ok",
"memory_ready": true,
"readiness_state": "ready_rich",
"triage": { "decision": "retrieve", "reasoning": "..." },
"diagnostics": {
"request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
"duration_ms": 38420,
"estimated_tokens": 6200,
"gemini_calls_estimate": 3
}
},
"isError": false
},
"duration_ms": 38420,
"created_at": "2026-05-29T11:47:33.128000+00:00"
}
```
## Пов'язані розділи
* [Налаштування та ключі](/docs/uk/setup-and-keys) — формат ключа та безпека
* [Довідник MCP](/docs/uk/mcp-reference) — протокол Memory MCP
* [Квоти та ліміти](/docs/uk/quotas-and-limits) — що враховується в лімітах