openapi: 3.1.0 info: title: POSnavigator Agent Platform Metrics API version: "1.0.0" description: |- Admin-only traffic aggregates for agent discovery and /api/agent calls — the same numbers as the admin Agent Platform panel. Requires X-Api-Key, agent-analytics:read, and an admin key owner. Query days 1-90, default 7. Event types: discovery (crawls of llms.txt/agents.json — not proof of LLM use), schema, recommend (real ranking calls), terminal_quote, device_info, company_search, register, lead, checkout, rate_limited, fraud_signal. # The happy path 1. GET /openapi/agent-platform-metrics.yaml 2. GET /api/v1/agent-platform/metrics?days=7 Send `X-Api-Key: ` on every operation except this document itself. Create a key at /user/api-keys. Format: `pn_` plus a random string. Copy it immediately; it is shown once. Default new keys include blog, legal, presetfilter, versus-landing, widget, agent-analytics and hero-analytics scopes. Missing scopes return 403 INSUFFICIENT_PERMISSIONS. Bank-scoped resources also require the key owner to be admin or listed on that bank; otherwise 403 FORBIDDEN. # Response envelope Success: `{ "success": true, "data": ... }`. Failure: `{ "success": false, "error": { "code", "message" } }`. Branch on error.code, never on error.message. # Error codes | code | status | what to do | | --- | --- | --- | | MISSING_API_KEY | 401 | add X-Api-Key; do not retry blindly | | INVALID_API_KEY | 401 | stop; ask a human for a new key | | INSUFFICIENT_PERMISSIONS | 403 | stop; this key lacks a required scope | | FORBIDDEN | 403 | stop or switch to a key with bank/admin access | | RATE_LIMIT_EXCEEDED | 429 | wait Retry-After seconds | | INTERNAL_ERROR | 500 | retry with backoff | # Rate limiting Every response after successful authentication carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 also carries Retry-After. The two 401s are emitted before rate-limit accounting. Default window is 100 requests per rolling hour unless the key was configured otherwise. # Canonical host Use https://posnavigator.eu. Legacy .hu hosts redirect; authenticated writes should call .eu directly. Additional codes: INVALID_QUERY 400. servers: - url: https://posnavigator.eu tags: - name: Discovery - name: Metrics security: - ApiKeyAuth: [] paths: /openapi/agent-platform-metrics.yaml: get: operationId: getAgentPlatformMetricsOpenApi tags: [Discovery] security: [] summary: Public OpenAPI 3.1 description description: |- This document. Public: no API key, no rate limit. Fetch it first and treat it as the complete manual. Every schema, limit, example, error code and header an agent needs is here. Linked from GET /openapi/catalog.yaml. Data operations below require authentication as described in info. responses: '200': description: OpenAPI YAML content: application/yaml: schema: type: string example: 'openapi: 3.1.0' /api/v1/agent-platform/metrics: get: operationId: getAgentPlatformMetrics tags: [Metrics] summary: Agent discovery and API traffic aggregates description: |- Returns periodDays, periodStart/End, eventsByType (total/success/failed), eventBreakdown with practicalMeaning and confidence, sponsoredTop3Violations, and userAgentBreakdown. Treat discovery as crawl volume. Treat recommend as actual agent ranking use. Admin + agent-analytics:read required. parameters: - name: days in: query schema: { type: integer, minimum: 1, maximum: 90, default: 7 } description: Lookback window in days responses: '200': description: Metrics headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/AgentMetricsResponse' example: success: true data: periodDays: 7 eventsByType: discovery: { total: 41, success: 41, failed: 0 } recommend: { total: 0, success: 0, failed: 0 } '400': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Error headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: |- Send `X-Api-Key: pn_...` on every data operation. Create a key at /user/api-keys; it is shown once. Inactive or expired keys return 401. headers: X-RateLimit-Limit: description: Maximum requests allowed in the current window schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: Unix epoch seconds when the window resets schema: type: integer Retry-After: description: Seconds to wait before retrying a 429 schema: type: integer parameters: BankId: name: bankId in: path required: true description: 24-character hex Mongo ObjectId of the bank schema: type: string pattern: '^[a-fA-F0-9]{24}$' maxLength: 24 schemas: ErrorEnvelope: type: object additionalProperties: false required: [success, error] properties: success: type: boolean const: false error: type: object additionalProperties: false required: [code, message] properties: code: type: string maxLength: 80 description: Stable machine code. Branch on this, never on message. message: type: string maxLength: 2000 details: type: array maxItems: 50 items: type: string maxLength: 500 retryAfter: type: integer description: Present on RATE_LIMIT_EXCEEDED field_errors: type: object additionalProperties: type: array maxItems: 20 items: type: string maxLength: 500 LocalePair: type: object additionalProperties: false properties: hu: type: string maxLength: 20000 en: type: string maxLength: 20000 OffsetPagination: type: object additionalProperties: false required: [total, limit, offset, hasMore] properties: total: type: integer limit: type: integer offset: type: integer hasMore: type: boolean AgentMetricsResponse: type: object required: [success, data] additionalProperties: false properties: success: { type: boolean, const: true } data: type: object additionalProperties: true properties: periodDays: { type: integer } periodStart: { type: string, maxLength: 40 } periodEnd: { type: string, maxLength: 40 } eventsByType: type: object additionalProperties: type: object additionalProperties: true eventBreakdown: type: array maxItems: 40 items: { type: object, additionalProperties: true } sponsoredTop3Violations: { type: integer } userAgentBreakdown: type: array maxItems: 200 items: { type: object, additionalProperties: true }