Огляд API для розробників

Developer API підтримує сторінки Memory MCP у застосунку PAM (Setup, Access, Usage, Request Log). Використовуйте його для програмного керування Memory MCP, перевірки readiness та перегляду історії retrieval.

Ці endpoints — не протокол Memory MCP. Для retrieval агентом використовуйте POST /v1/mcp/memory — див. Довідник MCP.

Автентифікація

Developer API endpoints потребують PAM access JWT у заголовку Authorization:

Authorization: Bearer <access_token>

Це відрізняється від автентифікації Memory MCP, яка підтримує обидва варіанти:

Тип auth	Для чого	Формат заголовка
`pam_mkey`	Memory MCP (`/v1/mcp/memory`) — desktop/скрипт	`Authorization: pam_mkey_<key>`
OAuth Bearer	Memory MCP (`/v1/mcp/memory`) — браузерні LLM	`Authorization: Bearer <opaque_access_token>`
Access JWT	Developer API (`/v1/dev/*`)	`Authorization: Bearer <token>`

Браузерні клієнти знаходять 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.

Типові сценарії

Перевірити readiness перед підключенням агента

Викличте GET /v1/dev/readiness і переконайтеся, що ready: true, перш ніж тестувати retrieve_memory з MCP-клієнта.

Отримати актуальний MCP-конфіг для акаунта

Викличте GET /v1/dev/mcp-config, коли потрібні account-specific деталі підключення MCP в одній відповіді. Див. поля mcp-config нижче — більшості інтеграцій достатньо підмножини полів.

Оновити скомпрометований ключ

Викличте POST /v1/dev/rotate-key із access JWT. Одразу скопіюйте новий api_key і оновіть конфігурацію MCP-клієнта.

Діагностувати невдалий retrieval

Викличте 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_<prefix>`)
`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`	Той самий текст, що в Швидкому старті, крок 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

Приклад відповіді (скорочено)

{
  "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_<key>"
        }
      }
    }
  },
  "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`

{
  "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 пояснює очікування:

{
  "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.

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

{
  "revoked": true
}

`GET /v1/dev/oauth-connections`

Один елемент списку на сім’ю refresh token. expires_at — термін refresh token, якщо є.

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

{
  "revoked": true,
  "id": 42
}

`GET /v1/dev/mcp-usage-stats?days=30`

Щоденна серія містить кожен календарний день у діапазоні (нулі, якщо активності не було). У hourly_heatmap поле weekday: 0 = неділя, 6 = субота.

{
  "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). Текстові поля в прикладі можуть бути скорочені.

{
  "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 і відповідь.

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

Пов’язані розділи

Налаштування та ключі — формат ключа та безпека
Довідник MCP — протокол Memory MCP
Квоти та ліміти — що враховується в лімітах

Getting started

Reference

Огляд API для розробників

Автентифікація

Base URL

Endpoints

Не враховуються в MCP-квотах

Типові сценарії

Поля mcp-config

Для налаштування MCP

Опційні convenience-копії

Також у відповіді (для polling краще окремі endpoints)

Можна ігнорувати в коді

Приклад відповіді (скорочено)

Приклади відповідей

`GET /v1/dev/readiness`

`POST /v1/dev/rotate-key`

`POST /v1/dev/revoke-key`

`GET /v1/dev/oauth-connections`

`POST /v1/dev/oauth-connections/{connection_id}/revoke`

`GET /v1/dev/mcp-usage-stats?days=30`

`GET /v1/dev/mcp-requests?limit=10&page=1`

`GET /v1/dev/mcp-requests/{request_id}`

Пов’язані розділи

​Автентифікація

​Base URL

​Endpoints

​Не враховуються в MCP-квотах

​Типові сценарії

​Поля mcp-config

​Для налаштування MCP

​Опційні convenience-копії

​Також у відповіді (для polling краще окремі endpoints)

​Можна ігнорувати в коді

​Приклад відповіді (скорочено)

​Приклади відповідей

​GET /v1/dev/readiness

​POST /v1/dev/rotate-key

​POST /v1/dev/revoke-key

​GET /v1/dev/oauth-connections

​POST /v1/dev/oauth-connections/{connection_id}/revoke

​GET /v1/dev/mcp-usage-stats?days=30

​GET /v1/dev/mcp-requests?limit=10&page=1

​GET /v1/dev/mcp-requests/{request_id}

​Пов’язані розділи

Автентифікація

Base URL

Endpoints

Не враховуються в MCP-квотах

Типові сценарії

Поля mcp-config

Для налаштування MCP

Опційні convenience-копії

Також у відповіді (для polling краще окремі endpoints)

Можна ігнорувати в коді

Приклад відповіді (скорочено)

Приклади відповідей

`GET /v1/dev/readiness`

`POST /v1/dev/rotate-key`

`POST /v1/dev/revoke-key`

`GET /v1/dev/oauth-connections`

`POST /v1/dev/oauth-connections/{connection_id}/revoke`

`GET /v1/dev/mcp-usage-stats?days=30`

`GET /v1/dev/mcp-requests?limit=10&page=1`

`GET /v1/dev/mcp-requests/{request_id}`

Пов’язані розділи