openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Actors API
  description: "The HubSpot Analytics Events API allows you to retrieve event completion data \nfrom your HubSpot account. Use this API to query event instances associated with \nCRM objects, filter by event types, and analyze user behavior and engagement patterns.\n\n## Key Features\n- Retrieve event instances for CRM objects\n- Filter events by type, date range, and object\n- Paginate through large result sets\n- Query available event types\n"
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server
tags:
- name: Actors
  description: Operations for managing conversation participants including visitors and agents.
paths:
  /conversations/v3/conversations/actors:
    get:
      tags:
      - Actors
      operationId: listActors
      summary: Hubspot List Actors
      description: 'Retrieve a list of conversation actors (participants) in your account.

        Actors can be visitors, agents, or bots who participate in conversations.

        '
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - conversations.read
      - PrivateApp: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of actors per page
        example: 20
      - name: after
        in: query
        schema:
          type: string
        description: Pagination cursor for the next page
        example: NTI1Cg%3D%3D
      responses:
        '200':
          description: Successfully retrieved the list of actors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorCollection'
              examples:
                Success:
                  $ref: '#/components/examples/ActorCollectionExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /conversations/v3/conversations/actors/{actorId}:
    get:
      tags:
      - Actors
      operationId: getActorById
      summary: Hubspot Retrieve an Actor
      description: 'Retrieve a specific actor by their unique identifier.

        Returns complete details about the conversation participant.

        '
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - conversations.read
      - PrivateApp: []
      parameters:
      - name: actorId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the actor to retrieve
        example: actor_101
      responses:
        '200':
          description: Successfully retrieved the actor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Actor'
              examples:
                Success:
                  $ref: '#/components/examples/ActorExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ErrorDetail:
      type: object
      description: Detailed information about a specific error.
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid thread ID format
        code:
          type: string
          description: Error code
          example: INVALID_FORMAT
        subCategory:
          type: string
          description: Error subcategory
          example: PARAMETER_ERROR
        in:
          type: string
          description: Location where error occurred
          example: path
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
      required:
      - message
    ActorCollection:
      type: object
      description: Paginated collection of actors
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
          description: Array of actor records
          example:
          - id: actor_101
            actorId: actor_101
            name: John Customer
            email: john@example.com
            type: VISITOR
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - results
    Error:
      type: object
      description: Standard error response structure.
      properties:
        category:
          type: string
          description: Error category
          example: VALIDATION_ERROR
        correlationId:
          type: string
          format: uuid
          description: Unique tracking identifier for support requests
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message:
          type: string
          description: Human-readable error message
          example: Invalid input parameters
        subCategory:
          type: string
          description: Error subcategory
          example: INVALID_PARAMETER
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example:
          - message: Invalid thread ID format
            code: INVALID_FORMAT
            subCategory: PARAMETER_ERROR
            in: path
            context:
              key: value
      required:
      - category
      - correlationId
      - message
    Paging:
      type: object
      description: Pagination information for list responses.
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'
    PagingNext:
      type: object
      description: Pagination cursor information for retrieving the next page.
      properties:
        after:
          type: string
          description: Cursor token for the next page
          example: NTI1Cg%3D%3D
        link:
          type: string
          description: API link to the next page
          example: /conversations/v3/conversations/inboxes?after=NTI1Cg%3D%3D
    Actor:
      type: object
      description: Represents a participant in a conversation (visitor, agent, or bot).
      properties:
        id:
          type: string
          description: Unique identifier for the actor
          example: actor_101
        actorId:
          type: string
          description: Actor ID reference
          example: actor_101
        name:
          type: string
          description: Display name of the actor
          example: John Customer
        email:
          type: string
          format: email
          description: Email address of the actor
          example: john@example.com
        type:
          type: string
          description: Type of actor (e.g., VISITOR, AGENT, BOT)
          example: VISITOR
      required:
      - id
  responses:
    ErrorResponse:
      description: An error occurred while processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'
  examples:
    ActorCollectionExample:
      summary: Paginated list of actors
      value:
        results:
        - id: actor_101
          actorId: actor_101
          name: John Customer
          email: john@example.com
          type: VISITOR
        - id: actor_agent_123
          actorId: actor_agent_123
          name: Support Agent
          email: support@example.com
          type: AGENT
        paging:
          next:
            after: NTI1Cg%3D%3D
            link: /conversations/v3/conversations/actors?after=NTI1Cg%3D%3D
    ErrorExample:
      summary: Validation error response
      value:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: Invalid input parameters
        context:
          invalidFields:
          - threadId
    ActorExample:
      summary: A complete actor record
      value:
        id: actor_101
        actorId: actor_101
        name: John Customer
        email: john@example.com
        type: VISITOR
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            analytics.read: Read analytics data