HubSpot Authors API

openapi: 3.1.0
info:
  title: HubSpot Blog Authors API
  description: |
    The HubSpot Blog Authors API enables you to manage author information for your 
    blog posts. Create, update, retrieve, and delete blog author profiles, manage 
    multi-language author groups, and perform batch operations on multiple authors 
    at once.

    ## Key Features
    - CRUD operations for blog author profiles
    - Batch operations for bulk author management
    - Multi-language support with language variations
    - Author profile customization with social links
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-hubspot-product-tier-requirements:
    marketing: PROFESSIONAL
    cms: STARTER

servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server

tags:
- name: Batch Operations
  description: Perform bulk operations on multiple blog authors simultaneously
- name: Blog Authors
  description: Create, read, update, and delete individual blog author profiles
- name: Multi-Language Management
  description: Manage multi-language author groups and language variations

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            content: Read from and write to content
    PrivateApp:
      type: apiKey
      name: private-app
      in: header

  schemas:
    BlogAuthor:
      type: object
      description: Represents a blog author profile with biographical and social information
      properties:
        id:
          type: string
          description: Unique identifier for the blog author
          example: '500123'
        name:
          type: string
          description: Full display name of the author
          example: Example Record
        slug:
          type: string
          description: URL-friendly identifier for the author
          example: example-value
        email:
          type: string
          format: email
          description: Author's email address
          example: [email protected]
        bio:
          type: string
          description: Author biography or description
          example: example-value
        website:
          type: string
          format: uri
          description: Author's personal website URL
          example: https://app.hubspot.com/contacts/12345
        twitter:
          type: string
          description: Author's Twitter/X handle
          example: example-value
        facebook:
          type: string
          description: Author's Facebook profile URL
          example: example-value
        linkedin:
          type: string
          description: Author's LinkedIn profile URL
          example: https://app.hubspot.com/contacts/12345
        avatar:
          type: string
          format: uri
          description: URL to the author's avatar image
          example: https://app.hubspot.com/contacts/12345
        language:
          type: string
          description: Language code for the author profile (e.g., en, es, fr)
          example: en
        translatedFromId:
          type: string
          description: ID of the original author this was translated from
          example: '500123'
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the author was created
          example: '2025-03-15T14:30:00Z'
        updated:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the author was last updated
          example: '2025-03-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the author was archived
          example: '2025-03-15T14:30:00Z'
      required:
      - id
      - name
      - created
      - updated

    BlogAuthorInput:
      type: object
      description: Input data for creating or updating a blog author
      properties:
        name:
          type: string
          description: Full display name of the author
          example: Example Record
        slug:
          type: string
          description: URL-friendly identifier for the author
          example: example-value
        email:
          type: string
          format: email
          description: Author's email address
          example: [email protected]
        bio:
          type: string
          description: Author biography or description
          example: example-value
        website:
          type: string
          format: uri
          description: Author's personal website URL
          example: https://app.hubspot.com/contacts/12345
        twitter:
          type: string
          description: Author's Twitter/X handle
          example: example-value
        facebook:
          type: string
          description: Author's Facebook profile URL
          example: example-value
        linkedin:
          type: string
          description: Author's LinkedIn profile URL
          example: https://app.hubspot.com/contacts/12345
        avatar:
          type: string
          format: uri
          description: URL to the author's avatar image
          example: https://app.hubspot.com/contacts/12345
      required:
      - name

    BlogAuthorCollection:
      type: object
      description: Paginated collection of blog authors
      properties:
        total:
          type: integer
          description: Total number of authors matching the query
          example: 10
        results:
          type: array
          items:
            $ref: '#/components/schemas/BlogAuthor'
          description: Array of blog authors
          example:
          - id: '500123'
            name: Example Record
            slug: example-value
            email: [email protected]
            bio: example-value
            website: https://app.hubspot.com/contacts/12345
            twitter: example-value
            facebook: example-value
            linkedin: https://app.hubspot.com/contacts/12345
            avatar: https://app.hubspot.com/contacts/12345
            language: en
            translatedFromId: '500123'
            created: '2025-03-15T14:30:00Z'
            updated: '2025-03-15T14:30:00Z'
            deletedAt: '2025-03-15T14:30:00Z'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - total
      - results

    BatchInputItem:
      type: object
      description: Single item in a batch update operation
      properties:
        id:
          type: string
          description: ID of the author to update
          example: '500123'
        properties:
          $ref: '#/components/schemas/BlogAuthorInput'
      required:
      - id

    BatchInput:
      type: object
      description: Input for batch update operations
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/BatchInputItem'
          description: Array of items to process
          example:
          - id: '500123'
            properties: {}
      required:
      - inputs

    BatchReadInput:
      type: object
      description: Input for batch read operations
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: ID of the author to read
            required:
            - id
          description: Array of author IDs to retrieve
          example:
          - id: '500123'
      required:
      - inputs

    BatchCreateInput:
      type: object
      description: Input for batch create operations
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/BlogAuthorInput'
          description: Array of authors to create
          example:
          - name: Example Record
            slug: example-value
            email: [email protected]
            bio: example-value
            website: https://app.hubspot.com/contacts/12345
            twitter: example-value
            facebook: example-value
            linkedin: https://app.hubspot.com/contacts/12345
            avatar: https://app.hubspot.com/contacts/12345
      required:
      - inputs

    BatchArchiveInput:
      type: object
      description: Input for batch archive operations
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: ID of the author to archive
            required:
            - id
          description: Array of author IDs to archive
          example:
          - id: '500123'
      required:
      - inputs

    BatchResponse:
      type: object
      description: Response from batch operations
      properties:
        status:
          type: string
          enum:
          - PENDING
          - PROCESSING
          - CANCELED
          - COMPLETE
          description: Current status of the batch operation
          example: PENDING
        results:
          type: array
          items:
            $ref: '#/components/schemas/BlogAuthor'
          description: Successfully processed authors
          example:
          - id: '500123'
            name: Example Record
            slug: example-value
            email: [email protected]
            bio: example-value
            website: https://app.hubspot.com/contacts/12345
            twitter: example-value
            facebook: example-value
            linkedin: https://app.hubspot.com/contacts/12345
            avatar: https://app.hubspot.com/contacts/12345
            language: en
            translatedFromId: '500123'
            created: '2025-03-15T14:30:00Z'
            updated: '2025-03-15T14:30:00Z'
            deletedAt: '2025-03-15T14:30:00Z'
        requestedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the batch was requested
          example: '2025-03-15T14:30:00Z'
        startedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when processing started
          example: '2025-03-15T14:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when processing completed
          example: '2025-03-15T14:30:00Z'
        links:
          type: object
          additionalProperties:
            type: string
          description: Related links for the batch operation
          example:
            key: value
      required:
      - status
      - results
      - startedAt
      - completedAt

    BatchResponseWithErrors:
      allOf:
      - $ref: '#/components/schemas/BatchResponse'
      - type: object
        properties:
          numErrors:
            type: integer
            description: Number of errors encountered during processing
          errors:
            type: array
            items:
              $ref: '#/components/schemas/StandardError'
            description: List of errors encountered

    DetachFromLanguageGroupRequest:
      type: object
      description: Request to detach an author from a multi-language group
      properties:
        id:
          type: string
          description: ID of the author to detach
          example: '500123'
      required:
      - id

    SetLanguagePrimaryRequest:
      type: object
      description: Request to set a new primary language for a multi-language group
      properties:
        id:
          type: string
          description: ID of the author to set as primary
          example: '500123'
      required:
      - id

    AttachToLanguageGroupRequest:
      type: object
      description: Request to attach an author to a multi-language group
      properties:
        id:
          type: string
          description: ID of the author to attach
          example: '500123'
        language:
          type: string
          description: Language code for the author (e.g., es, fr, de)
          example: en
        primaryId:
          type: string
          description: ID of the primary language author
          example: '500123'
        primaryLanguage:
          type: string
          description: Language code of the primary author
          example: en
      required:
      - id
      - language
      - primaryId

    CreateLanguageVariationRequest:
      type: object
      description: Request to create a language variation of an author
      properties:
        id:
          type: string
          description: ID of the source author
          example: '500123'
        language:
          type: string
          description: Language code for the new variation
          example: en
      required:
      - id
      - language

    Paging:
      type: object
      description: Pagination information for navigating result sets
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'

    PagingNext:
      type: object
      description: Pagination cursor for retrieving the next page of results
      properties:
        after:
          type: string
          description: Cursor token for the next page
          example: example-value
        link:
          type: string
          description: API link to the next page of results

          example: https://app.hubspot.com/contacts/12345
    StandardError:
      type: object
      description: Standard error in batch operations
      properties:
        status:
          type: string
          description: Error status code
          example: active
        id:
          type: string
          description: ID of the failed item
          example: '500123'
        category:
          type: string
          description: Error category
          example: standard
        message:
          type: string
          description: Human-readable error message
          example: This is an example description.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          description: List of detailed errors
          example:
          - message: This is an example description.
            code: example-value
            subCategory: standard
            in: example-value
            context:
              key: value
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional error context
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          description: Related links for error resolution
          example:
            key: value
      required:
      - status
      - category
      - message

    ErrorDetail:
      type: object
      description: Detailed information about a specific error
      properties:
        message:
          type: string
          description: Human-readable error message
          example: This is an example description.
        code:
          type: string
          description: Machine-readable error code
          example: example-value
        subCategory:
          type: string
          description: Specific error subcategory
          example: standard
        in:
          type: string
          description: Location where the error occurred
          example: example-value
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional context about the error
          example: &id001
            key: value
      required:
      - message

    Error:
      type: object
      description: Standard error response returned when an API request fails
      properties:
        category:
          type: string
          description: High-level error category
          example: standard
        correlationId:
          type: string
          format: uuid
          description: Unique identifier for tracking and debugging
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
          description: Human-readable error message
          example: This is an example description.
        subCategory:
          type: string
          description: Specific error subcategory
          example: standard
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional error context
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          description: Related links for error resolution
          example:
            key: value
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          description: List of specific errors
          example:
          - message: This is an example description.
            code: example-value
            subCategory: standard
            in: example-value
            context: *id001
      required:
      - category
      - correlationId
      - message

  examples:
    BlogAuthorExample:
      summary: Complete blog author profile
      value:
        id: "12345678901"
        name: "Jane Smith"
        slug: "jane-smith"
        email: "[email protected]"
        bio: "Jane is a senior content strategist with 10 years of experience in digital marketing."
        website: "https://janesmith.com"
        twitter: "@janesmith"
        linkedin: "https://linkedin.com/in/janesmith"
        avatar: "https://example.com/avatars/jane-smith.jpg"
        language: "en"
        created: "2024-01-15T10:30:00Z"
        updated: "2024-01-20T14:45:00Z"

    BlogAuthorInputExample:
      summary: Blog author creation input
      value:
        name: "Jane Smith"
        slug: "jane-smith"
        email: "[email protected]"
        bio: "Jane is a senior content strategist with 10 years of experience in digital marketing."
        website: "https://janesmith.com"
        twitter: "@janesmith"

    BlogAuthorCollectionExample:
      summary: Paginated list of blog authors
      value:
        total: 25
        results:
        - id: "12345678901"
          name: "Jane Smith"
          slug: "jane-smith"
          email: "[email protected]"
          bio: "Senior content strategist"
          language: "en"
          created: "2024-01-15T10:30:00Z"
          updated: "2024-01-20T14:45:00Z"
        - id: "12345678902"
          name: "John Doe"
          slug: "john-doe"
          email: "[email protected]"
          bio: "Technical writer and developer advocate"
          language: "en"
          created: "2024-01-10T09:00:00Z"
          updated: "2024-01-18T11:30:00Z"
        paging:
          next:
            after: "NTI1Cg%3D%3D"
            link: "/cms/v3/blogs/authors?after=NTI1Cg%3D%3D"

    BatchResponseExample:
      summary: Successful batch operation response
      value:
        status: "COMPLETE"
        results:
        - id: "12345678901"
          name: "Jane Smith"
          slug: "jane-smith"
          created: "2024-01-15T10:30:00Z"
          updated: "2024-01-20T14:45:00Z"
        requestedAt: "2024-01-20T14:44:00Z"
        startedAt: "2024-01-20T14:44:01Z"
        completedAt: "2024-01-20T14:45:00Z"

    BatchReadInputExample:
      summary: Batch read input
      value:
        inputs:
        - id: "12345678901"
        - id: "12345678902"

    ErrorExample:
      summary: Validation error response
      value:
        category: "VALIDATION_ERROR"
        correlationId: "aeb5f871-7f07-4993-9211-075dc63e7cbf"
        message: "Invalid input (details will vary based on the error)"
        links:
          knowledge-base: "https://www.hubspot.com/products/service/knowledge-base"

  responses:
    ErrorResponse:
      description: An error occurred while processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'

paths:
  /cms/v3/blogs/authors:
    get:
      tags:
      - Blog Authors
      operationId: listBlogAuthors
      summary: Hubspot List All Blog Authors
      description: |
        Retrieve a paginated list of all blog authors in your HubSpot account. 
        Use query parameters to filter, sort, and paginate the results.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of results per page (1-100)
        example: 20
      - name: after
        in: query
        schema:
          type: string
        description: Pagination cursor for the next page
        example: example-value
      - name: sort
        in: query
        schema:
          type: array
          items:
            type: string
        description: Properties to sort by
        example:
        - example-value
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to return archived authors
        example: false
      - name: property
        in: query
        schema:
          type: string
        description: Specific property to return
        example: example-value
      responses:
        '200':
          description: Successfully retrieved blog authors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogAuthorCollection'
              examples:
                Success:
                  $ref: '#/components/examples/BlogAuthorCollectionExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    post:
      tags:
      - Blog Authors
      operationId: createBlogAuthor
      summary: Hubspot Create a Blog Author
      description: Create a new blog author profile in your HubSpot account.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      requestBody:
        required: true
        description: Blog author data to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlogAuthorInput'
            examples:
              CreateAuthor:
                $ref: '#/components/examples/BlogAuthorInputExample'
      responses:
        '201':
          description: Successfully created blog author
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogAuthor'
              examples:
                Success:
                  $ref: '#/components/examples/BlogAuthorExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /cms/v3/blogs/authors/{objectId}:
    get:
      tags:
      - Blog Authors
      operationId: getBlogAuthorById
      summary: Hubspot Retrieve a Blog Author
      description: Retrieve a specific blog author by their unique identifier.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: objectId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the blog author
        example: "12345678901"
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to return archived authors
        example: false
      - name: property
        in: query
        schema:
          type: string
        description: Specific property to return
        example: example-value
      responses:
        '200':
          description: Successfully retrieved blog author
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogAuthor'
              examples:
                Success:
                  $ref: '#/components/examples/BlogAuthorExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    patch:
      tags:
      - Blog Authors
      operationId: updateBlogAuthor
      summary: Hubspot Update a Blog Author
      description: |
        Update an existing blog author. Only the properties included in the 
        request body will be updated; all other properties remain unchanged.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: objectId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the blog author
        example: "12345678901"
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to update archived authors
        example: false
      requestBody:
        required: true
        description: Blog author properties to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlogAuthorInput'
            examples:
              UpdateAuthor:
                $ref: '#/components/examples/BlogAuthorInputExample'
      responses:
        '200':
          description: Successfully updated blog author
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogAuthor'
              examples:
                Success:
                  $ref: '#/components/examples/BlogAuthorExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    delete:
      tags:
      - Blog Authors
      operationId: archiveBlogAuthor
      summary: Hubspot Archive a Blog Author
      description: Archive (soft delete) a blog author by their unique identifier.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: objectId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the blog author
        example: "12345678901"
      - name: archived
        in: query
        schema:
          type: boolean
        description: Whether to return archived authors
        example: true
      responses:
        '204':
          description: Successfully archived blog author
        default:
          $ref: '#/components/responses/ErrorResponse'

  /cms/v3/blogs/authors/batch/read:
    post:
      tags:
      - Batch Operations
      operationId: batchReadBlogAuthors
      summary: Hubspot Read Multiple Blog Authors
      description: Retrieve multiple blog authors by their IDs in a single request.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to include archived authors
        example: false
      requestBody:
        required: true
        description: List of author IDs to retrieve
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReadInput'
            examples:
              BatchRead:
                $ref: '#/components/examples/BatchReadInputExample'
      responses:
        '200':
          description: Successfully retrieved blog authors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              examples:
                Success:
                  $ref: '#/components/examples/BatchResponseExample'
        '207':
          description: Partial success with some errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseWithErrors'
              examples:
                Batchreadblogauthors207Example:
                  summary: Default batchReadBlogAuthors 207 response
                  x-microcks-default: true
                  value: example-value
        default:
          $ref: '#/components/responses/ErrorResponse'

  /cms/v3/blogs/authors/batch/create:
    post:
      tags:
      - Batch Operations
      operationId: batchCreateBlogAuthors
      summary: Hubspot Create Multiple Blog Authors
      description: Create multiple blog authors in a single request.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      requestBody:
        required: true
        description: List of blog authors to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateInput'
            example:
              inputs:
              - name: "Jane Smith"
                slug: "jane-smith"
                email: "[email protected]"
              - name: "John Doe"
                slug: "john-doe"
                email: "[email protected]"
      responses:
        '201':
          description: Successfully created blog authors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              examples:
                Success:
                  $ref: '#/components/examples/BatchResponseExample'
        '207':
          description: Partial success with some errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseWithErrors'
              examples:
                Batchcreateblogauthors207Example:
                  summary: Default batchCreateBlogAuthors 207 response
                  x-microcks-default: true
                  value: example-value
        default:
          $ref: '#/components/responses/ErrorResponse'

  /cms/v3/blogs/authors/batch/update:
    post:
      tags:
      - Batch Operations
      operationId: batchUpdateBlogAuthors
      summary: Hubspot Update Multiple Blog Authors
      description: Update multiple blog authors in a single request.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      parameters:
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to update archived authors
        example: false
      requestBody:
        required: true
        description: List of blog authors to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInput'
            example:
              inputs:
              - id: "12345678901"
                properties:
                  bio: "Updated bio content"
              - id: "12345678902"
                properties:
                  bio: "Another updated bio"
      responses:
        '200':
          description: Successfully updated blog authors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
              examples:
                Success:
                  $ref: '#/components/examples/BatchResponseExample'
        '207':
          description: Partial success with some errors
          content:
            application/json:
              schema:
                $ref: '#/components/sc

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-authors-api-openapi.yml