openapi: 3.2.0
info:
  title: Gtm Linkedin Benchmarks API
  version: '1.0'
  contact:
    name: GTM API
    url: https://gtm-api.com
    email: support@gtm-api.com
  license:
    name: Proprietary
    url: https://gtm-api.com/license
  description: 'Operations tagged linkedin_benchmarks across 2 of this provider''s published API definitions: gtm-api-openapi-openapi.yml, gtm-api-linkedin-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.gtm-api.com/linkedin/v4
  description: Production, through the app.gtm-api.com gateway
security:
- BearerJwt: []
  TeamSid: []
tags:
- name: linkedin_benchmarks
  description: Registry package `mcp.linkedin/linkedin_benchmarks`, served on MCP mount `linkedin.account-monitor`.
paths:
  /api/linkedin-benchmarks/get-latest-benchmark:
    post:
      operationId: get_latest_linkedin_benchmark
      summary: Get latest LinkedIn benchmark
      description: 'Return the most recent platform benchmark row (largest period_start < today). Platform-GLOBAL: every team reads the same weekly row. No parameters. Use to compare an account or fleet against the market (acceptance rate, reply rates) and to calibrate safe daily ceilings by cohort. Pair it with linkedin-account-snapshots / linkedin-accounts / *.metrics for the per-account numbers to compare against. Every metric lives in the group_1 / group_2 / group_3 JSON blobs; dereference the specific path per MARKET_BENCHMARKS.md. NOT for a single account''s current numbers (linkedin-accounts / -snapshots), live limit utilisation (linkedin-account-smart-limits), a specific quota hit (linkedin-account-quota-hits), or historical trends (internal-only). Cold start returns 404 no_benchmark_published.


        Contract:

        - MCP tool `get_latest_linkedin_benchmark`, registry package `mcp.linkedin/linkedin_benchmarks`, mount `linkedin.account-monitor`.

        - Operation `action`, response envelope `action`.

        - Flags: read only.'
      tags:
      - linkedin_benchmarks
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLatestLinkedinBenchmarkResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
      x-gtm-mcp-tool: get_latest_linkedin_benchmark
      x-gtm-mcp-mount: linkedin.account-monitor
      x-gtm-entity: linkedin_benchmarks
      x-gtm-operation: action
      x-gtm-envelope: action
      x-gtm-availability: ga
      x-gtm-dangerous: false
      x-gtm-mass-action: false
      x-gtm-step-eligible: false
      x-gtm-schedule-required: false
      x-gtm-tool-class: trivial
    servers:
    - url: https://app.gtm-api.com/linkedin/v4
      description: Production, through the app.gtm-api.com gateway
components:
  responses:
    McpServerError:
      description: MCP error envelope with `error.code` internal_error or service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpClientError:
      description: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  schemas:
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - validation_failed
              - nothing_to_update
              - not_found
              - relation_not_found
              - invalid_transition
              - limit_exceeded
              - payment_required
              - duplicate_rejected
              - conflict
              - delete_blocked
              - unauthorized
              - forbidden
              - rate_limited
              - internal_error
              - service_unavailable
              - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                  - rule
                  - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Machine-readable blocker type (active_flow, pending_tasks, …).
                  severity:
                    type: string
                    enum:
                    - hard
                    - soft
                    description: hard = external action required; soft = acknowledge is enough.
                  description:
                    type: string
                  entity_sid:
                    type:
                    - string
                    - 'null'
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                - type
                - severity
                - description
                - entity_sid
                - resolution
                - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
          - code
          - message
          - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type:
              - string
              - 'null'
              description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
            actor_type:
              type:
              - string
              - 'null'
              description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.
          required:
          - trace_id
          - span_id
          - timestamp
          - duration_ms
      required:
      - success
      - error
    GetLatestLinkedinBenchmarkResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
        operation:
          type: string
          enum:
          - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          type:
          - object
          - 'null'
          properties:
            sid:
              type: string
            period_start:
              type: string
            period_end:
              type: string
            period_iso_week:
              type: string
            sample_size:
              type: number
            group_1:
              type: object
              additionalProperties: {}
              description: Business conversions (MARKET_BENCHMARKS.md §3).
            group_2:
              type: object
              additionalProperties: {}
              description: LinkedIn quota hits (§4).
            group_3:
              type: object
              additionalProperties: {}
              description: LinkedIn logouts (§5).
            created_at:
              type: string
          required:
          - sid
          - period_start
          - period_end
          - period_iso_week
          - sample_size
          - group_1
          - group_2
          - group_3
          - created_at
        result:
          type: object
          additionalProperties: {}
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type:
              - string
              - 'null'
              description: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
            actor_type:
              type:
              - string
              - 'null'
              description: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.
          required:
          - trace_id
          - span_id
          - timestamp
          - duration_ms
      required:
      - success
      - operation
      - action
      - item
      - result
      - meta
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token issued by gtm.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: Team scope for tokens that do not carry one. Ignored when the token already names a team.
x-refined-from:
- gtm-api-openapi-openapi.yml
- gtm-api-linkedin-openapi.yaml