Knock Accounts API

openapi: 3.2.0
info:
  title: Knock Management API (mAPI) Accounts API
  version: '1.0'
  description: Knock Management API (mAPI) — the resource-management surface for Knock. Programmatic CRUD over Workflows, Channels, Email Layouts, Partials, Templates, Translations, Audiences, Broadcasts, Guides, Message Types, Variables, Members, Channel Groups, Environments, Branches, Commits, and API Keys. Distinct from the runtime Knock API (api.knock.app) — mAPI lives at control.knock.app and is what powers the Knock CLI and MCP server.
  contact:
    name: Knock
    url: https://knock.app
servers:
- url: https://control.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: Resources for managing your Knock account.
  name: Accounts
paths:
  /v1/whoami:
    get:
      callbacks: {}
      description: Return information about the current calling scope. Will either be a service token or from an OAuth context.
      operationId: getWhoami
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoamiResponse'
          description: OK
      summary: Verify scope
      tags:
      - Accounts
components:
  schemas:
    WhoamiResponse:
      description: Information about the current calling scope.
      example:
        account_features:
          batch_items_render_limit_allowed: false
          custom_branding_allowed: false
          data_retention_days: 30
          data_warehouse_extension_allowed: false
          datadog_extension_allowed: true
          dsync_allowed: false
          guides_monthly_notified_recipients_limit: 500
          guides_per_tenant_scope_allowed: false
          heap_extension_allowed: false
          knock_branding_required: true
          litmus_email_preview_allowed: false
          message_sent_limit: 10000
          new_relic_extension_allowed: false
          segment_extension_allowed: false
          self_serve_allowed: true
          sso_allowed: false
          tenant_preferences_allowed: false
          translations_allowed: false
        account_name: Acme, Inc.
        account_slug: acme
        service_token_name: My Service Token
        type: service_token
        user_id: null
      properties:
        account_features:
          description: Account plan features and limits.
          properties:
            batch_items_render_limit_allowed:
              description: Whether batch rendering limits can be configured.
              type: boolean
              x-struct: null
              x-validate: null
            custom_branding_allowed:
              description: Whether custom branding can be applied to notifications.
              type: boolean
              x-struct: null
              x-validate: null
            data_retention_days:
              description: Number of days data is retained, null for unlimited retention.
              type:
              - integer
              - 'null'
              x-struct: null
              x-validate: null
            data_warehouse_extension_allowed:
              description: Whether data warehouse integration extensions are available.
              type: boolean
              x-struct: null
              x-validate: null
            datadog_extension_allowed:
              description: Whether Datadog integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            dsync_allowed:
              description: Whether directory sync functionality is available.
              type: boolean
              x-struct: null
              x-validate: null
            guides_monthly_notified_recipients_limit:
              description: Monthly limit for guide notification recipients, null for unlimited.
              type:
              - integer
              - 'null'
              x-struct: null
              x-validate: null
            guides_per_tenant_scope_allowed:
              description: Whether per-tenant scope for guide messages is allowed.
              type: boolean
              x-struct: null
              x-validate: null
            heap_extension_allowed:
              description: Whether Heap integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            knock_branding_required:
              description: Whether Knock branding is required to be displayed.
              type: boolean
              x-struct: null
              x-validate: null
            litmus_email_preview_allowed:
              description: Whether Litmus email preview integration is available.
              type: boolean
              x-struct: null
              x-validate: null
            message_sent_limit:
              description: Monthly limit for messages sent, null for unlimited.
              type:
              - integer
              - 'null'
              x-struct: null
              x-validate: null
            new_relic_extension_allowed:
              description: Whether New Relic integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            segment_extension_allowed:
              description: Whether Segment integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            self_serve_allowed:
              description: Whether self-service account management features are available.
              type: boolean
              x-struct: null
              x-validate: null
            sso_allowed:
              description: Whether single sign-on (SSO) is enabled for the account.
              type: boolean
              x-struct: null
              x-validate: null
            tenant_preferences_allowed:
              description: Whether tenant-level preferences are supported.
              type: boolean
              x-struct: null
              x-validate: null
            translations_allowed:
              description: Whether multi-language translations are supported.
              type: boolean
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        account_name:
          description: The display name of the account.
          type: string
          x-struct: null
          x-validate: null
        account_slug:
          description: The unique slug identifier for the account.
          type: string
          x-struct: null
          x-validate: null
        service_token_name:
          description: The name of the service token if authenticated via service token, null for OAuth contexts.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        type:
          description: The type of authentication context - either a service token or OAuth user context.
          enum:
          - service_token
          - oauth_context
          type: string
          x-struct: null
          x-validate: null
        user_id:
          description: The ID of the authenticated user if in OAuth context, null for service token contexts.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
      required:
      - account_name
      - account_slug
      - type
      - account_features
      title: WhoamiResponse
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WhoamiResponse
      x-validate: null
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock service token (kst_...) as a Bearer token.