API Evangelist enhancements for the Hootsuite Analytics REST API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Hootsuite Analytics REST API
  version: 1.0.0
x-provenance:
  generated: '2026-08-13'
  method: generated
  source: openapi/hootsuite-analytics-api-openapi.yml
  note: Captures API Evangelist enhancements only. The underlying OpenAPI is never mutated - apply this
    overlay to reproduce our annotated view.
extends: openapi/hootsuite-analytics-api-openapi.yml
actions:
- target: $.info
  description: Record where this contract came from and that it is first-party.
  update:
    x-api-evangelist:
      provider: Hootsuite
      provider-slug: hootsuite
      source: https://apidocs.hootsuite.com/docs/api/analytics/openapi/openapi.yaml
      discovered: '2026-08-13'
      catalog: https://apis.io/hootsuite
- target: $.info
  description: Attach the cross-cutting runtime semantics an agent needs and the spec does not state.
  update:
    x-conventions:
      authentication: 'OAuth 2.0 authorization code with refresh tokens, or the custom member_app /
        organization_app grants. Client credentials MUST go in an HTTP Basic header - Hootsuite does
        not accept them in the request body. Authorization codes are single-use and expire in 10 minutes;
        reusing one revokes every token issued from it. Refresh tokens never expire but are single-use.
        Discovery: https://platform.hootsuite.com/.well-known/oauth-authorization-server. See authentication/hootsuite-authentication.yml.'
      authorization: OAuth scope is not the authorization model. Only two scopes exist (offline, analytics:read);
        the real decision is the caller's Hootsuite dashboard role. A correctly scoped call can still
        403 with codes 4002-4010. See scopes/hootsuite-scopes.yml and https://developer.hootsuite.com/docs/api-permissions-matrix.
      errors: 'Errors use Hootsuite''s own envelope, not RFC 9457 problem+json: {"errors":[{"code":1234,"message":"...","id":"...","resource":{"type":"...","id":"..."}}]}.
        A partially-failed request returns BOTH data and errors in one 200 response - never treat a
        200 with a populated errors[] as clean. 97 numeric codes are catalogued in errors/hootsuite-problem-types.yml.
        OAuth endpoints return RFC 6749 bodies and SCIM endpoints return RFC 7644 bodies instead.'
      idempotency: NO IDEMPOTENCY. Hootsuite publishes no Idempotency-Key header and no replay-safe
        retry contract on any surface. A retried POST /v1/messages after a timeout can schedule the
        post twice. Before retrying a write, reconcile with GET /v1/messages and delete the duplicate
        with DELETE /v1/messages/{messageId} while it is still SCHEDULED. See conventions/hootsuite-conventions.yml.
      rate-limits: Hootsuite enforces 20 requests/second and a 100,000 call/day quota per account. Responses
        carry X-Account-Quota, X-Account-Quota-Used and X-Account-Rate-Limit-Requests-Remaining (reported
        per cluster node, so treat as a guide). Exhaustion returns HTTP 429 with error code 1003, 1004
        or 1043 and NO Retry-After header - back off until the end of the current one-second window.
        See rate-limits/hootsuite-rate-limits.yml.
      pagination: Cursor pagination only - no offset or page numbers. Cursors are opaque and returned
        in the response metadata block; echo them back verbatim. Invalid cursor format is error code
        3020.
      artifact: conventions/hootsuite-conventions.yml
- target: $.info
  description: Point at the API Evangelist artifacts derived from this specification.
  update:
    x-artifacts:
      conventions: conventions/hootsuite-conventions.yml
      errors: errors/hootsuite-problem-types.yml
      authentication: authentication/hootsuite-authentication.yml
      scopes: scopes/hootsuite-scopes.yml
      rate-limits: rate-limits/hootsuite-rate-limits.yml
      lifecycle: lifecycle/hootsuite-lifecycle.yml
      conformance: conformance/hootsuite-conformance.yml
      data-model: data-model/hootsuite-data-model.yml
      webhooks: asyncapi/hootsuite-webhooks.yml
      well-known: well-known/hootsuite-well-known.yml
      skills: skills/_index.yml
- target: $.paths.*.post
  description: Attach the batching limits Hootsuite documents outside the spec.
  update:
    x-agent-note: At most 10 social profile IDs (or 10 ad accounts, each paired with its owning organizationId)
      per request - batch beyond that. Maximum 100 results per call; a cursor is returned when more
      exist. reportingPeriod may start at most 2 years in the past and lastModified at most 30 days.
      Requires the analytics:read scope, which must first be enabled on the app itself in the developer
      portal. Not every social profile type returned by getSocialProfiles is supported for analytics
      - see https://developer.hootsuite.com/docs/networks-reference.
- target: $.info
  description: Record the June 2026 Facebook metric deprecations.
  update:
    x-deprecations: A set of Facebook profile and post metrics was deprecated on 2026-06-03 following
      upstream Facebook API changes. Historical data is still returned for dates before that. See https://developer.hootsuite.com/changelog/changes-to-facebook-metrics.