HubSpot Posts API

openapi: 3.1.0
info:
  title: HubSpot Blog Posts API
  description: |
    The HubSpot Blog Posts API enables you to manage blog posts programmatically. 
    Create, update, publish, and schedule blog posts, manage drafts and revisions, 
    handle multi-language content, and perform batch operations on multiple posts.

    ## Key Features
    - Full CRUD operations for blog posts
    - Publishing and scheduling capabilities
    - Draft and revision management
    - Multi-language support
    - Batch operations for bulk management
    - Post cloning functionality
  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 posts simultaneously
- name: Blog Posts
  description: Create, read, update, and delete individual blog posts
- name: Drafts and Revisions
  description: Manage blog post drafts and revision history
- name: Multi-Language Management
  description: Manage multi-language blog post groups and variations
- name: Post Cloning
  description: Clone and duplicate existing blog posts

- name: Publishing and Scheduling
  description: Schedule publication and manage post visibility
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:
    BlogPost:
      type: object
      description: Represents a blog post with all content and metadata
      properties:
        id:
          type: string
          description: Unique identifier for the blog post
          example: '500123'
        name:
          type: string
          description: Internal name of the blog post
          example: Example Record
        slug:
          type: string
          description: URL slug for the blog post
          example: example-value
        htmlTitle:
          type: string
          description: HTML title tag content
          example: Example Record
        postBody:
          type: string
          description: HTML content of the blog post body
          example: This is an example description.
        postSummary:
          type: string
          description: Summary or excerpt of the blog post
          example: example-value
        blogAuthorId:
          type: string
          description: ID of the associated blog author
          example: '500123'
        authorName:
          type: string
          description: Display name of the author
          example: Example Record
        contentGroupId:
          type: string
          description: ID of the blog this post belongs to
          example: '500123'
        campaign:
          type: string
          description: Campaign GUID associated with the post
          example: example-value
        categoryId:
          type: integer
          description: Category ID for the post
          example: 500123
        state:
          type: string
          enum:
          - DRAFT
          - DRAFT_AB
          - AUTOMATED
          - PUBLISHED
          - SCHEDULED
          - AUTOMATED_DRAFT
          description: Current state of the blog post
          example: DRAFT
        currentState:
          type: string
          description: Current state description
          example: active
        publishDate:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the post was/will be published
          example: '2025-03-15T14:30:00Z'
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the post was created
          example: '2025-03-15T14:30:00Z'
        updated:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the post was last updated
          example: '2025-03-15T14:30:00Z'
        archivedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the post was archived
          example: '2025-03-15T14:30:00Z'
        currentlyPublished:
          type: boolean
          description: Whether the post is currently published
          example: true
        domain:
          type: string
          description: Domain where the post is published
          example: example.hubspot.com
        featuredImage:
          type: string
          description: URL of the featured image
          example: example-value
        featuredImageAltText:
          type: string
          description: Alt text for the featured image
          example: example-value
        metaDescription:
          type: string
          description: Meta description for SEO
          example: This is an example description.
        headHtml:
          type: string
          description: Custom HTML for the head section
          example: example-value
        footerHtml:
          type: string
          description: Custom HTML for the footer section
          example: example-value
        language:
          type: string
          description: Language code of the blog post
          example: en
        translatedFromId:
          type: string
          description: ID of the original post this was translated from
          example: '500123'
        tagIds:
          type: array
          items:
            type: integer
          description: Array of tag IDs associated with the post
          example: &id001
          - 500123
        useFeaturedImage:
          type: boolean
          description: Whether to display the featured image
          example: true
        url:
          type: string
          format: uri
          description: Full URL of the published post
          example: https://app.hubspot.com/contacts/12345
        abStatus:
          type: string
          enum:
          - master
          - variant
          description: A/B test status
          example: master
        abTestId:
          type: string
          description: A/B test ID if part of a test
          example: '500123'
        folderId:
          type: string
          description: ID of the folder containing the post
          example: '500123'
      required:
      - id
      - name
      - created
      - updated

    BlogPostInput:
      type: object
      description: Input data for creating or updating a blog post
      properties:
        name:
          type: string
          description: Internal name of the blog post
          example: Example Record
        slug:
          type: string
          description: URL slug for the blog post
          example: example-value
        htmlTitle:
          type: string
          description: HTML title tag content
          example: Example Record
        postBody:
          type: string
          description: HTML content of the blog post body
          example: This is an example description.
        postSummary:
          type: string
          description: Summary or excerpt of the blog post
          example: example-value
        blogAuthorId:
          type: string
          description: ID of the associated blog author
          example: '500123'
        contentGroupId:
          type: string
          description: ID of the blog this post belongs to
          example: '500123'
        campaign:
          type: string
          description: Campaign GUID
          example: example-value
        publishDate:
          type: string
          format: date-time
          description: Scheduled publish date
          example: '2025-03-15T14:30:00Z'
        featuredImage:
          type: string
          description: URL of the featured image
          example: example-value
        featuredImageAltText:
          type: string
          description: Alt text for the featured image
          example: example-value
        metaDescription:
          type: string
          description: Meta description for SEO
          example: This is an example description.
        tagIds:
          type: array
          items:
            type: integer
          description: Tag IDs to associate
          example:
          - 500123
        useFeaturedImage:
          type: boolean
          description: Whether to display the featured image
          example: true
        language:
          type: string
          description: Language code
          example: en
      required:
      - name
      - contentGroupId

    BlogPostCollection:
      type: object
      description: Paginated collection of blog posts
      properties:
        total:
          type: integer
          description: Total number of posts matching the query
          example: 10
        results:
          type: array
          items:
            $ref: '#/components/schemas/BlogPost'
          description: Array of blog posts
          example:
          - id: '500123'
            name: Example Record
            slug: example-value
            htmlTitle: Example Record
            postBody: This is an example description.
            postSummary: example-value
            blogAuthorId: '500123'
            authorName: Example Record
            contentGroupId: '500123'
            campaign: example-value
            categoryId: 500123
            state: DRAFT
            currentState: active
            publishDate: '2025-03-15T14:30:00Z'
            created: '2025-03-15T14:30:00Z'
            updated: '2025-03-15T14:30:00Z'
            archivedAt: '2025-03-15T14:30:00Z'
            currentlyPublished: true
            domain: example.hubspot.com
            featuredImage: example-value
            featuredImageAltText: example-value
            metaDescription: This is an example description.
            headHtml: example-value
            footerHtml: example-value
            language: en
            translatedFromId: '500123'
            tagIds: *id001
            useFeaturedImage: true
            url: https://app.hubspot.com/contacts/12345
            abStatus: master
            abTestId: '500123'
            folderId: '500123'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - total
      - results

    ScheduleRequest:
      type: object
      description: Request to schedule a blog post for publication
      properties:
        id:
          type: string
          description: ID of the blog post to schedule
          example: '500123'
        publishDate:
          type: string
          format: date-time
          description: ISO 8601 date and time to publish
          example: '2025-03-15T14:30:00Z'
      required:
      - id
      - publishDate

    CloneRequest:
      type: object
      description: Request to clone a blog post
      properties:
        id:
          type: string
          description: ID of the blog post to clone
          example: '500123'
      required:
      - id

    PushLiveRequest:
      type: object
      description: Request to push draft changes live
      properties:
        id:
          type: string
          description: ID of the blog post
          example: '500123'
      required:
      - id

    ResetDraftRequest:
      type: object
      description: Request to reset draft to live version
      properties:
        id:
          type: string
          description: ID of the blog post
          example: '500123'
      required:
      - id

    RestorePreviousVersionRequest:
      type: object
      description: Request to restore a previous version
      properties:
        id:
          type: string
          description: ID of the blog post
          example: '500123'
        revisionId:
          type: string
          description: ID of the revision to restore
          example: '500123'
      required:
      - id
      - revisionId

    VersionHistory:
      type: object
      description: Version history entry for a blog post
      properties:
        id:
          type: string
          description: Version ID
          example: '500123'
        object:
          $ref: '#/components/schemas/BlogPost'
        user:
          type: object
          properties:
            id:
              type: string
            email:
              type: string
            fullName:
              type: string
          description: User who made the change
          example:
            id: '500123'
            email: [email protected]
            fullName: Example Record
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the version

          example: '2025-03-15T14:30:00Z'
    BatchInputItem:
      type: object
      description: Single item in a batch archive operation
      properties:
        id:
          type: string
          description: ID of the post to process
          example: '500123'
      required:
      - id

    BatchInput:
      type: object
      description: Input for batch archive operations
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/BatchInputItem'
          description: Array of items to process
          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/BlogPost'
          description: Successfully processed posts
          example:
          - id: '500123'
            name: Example Record
            slug: example-value
            htmlTitle: Example Record
            postBody: This is an example description.
            postSummary: example-value
            blogAuthorId: '500123'
            authorName: Example Record
            contentGroupId: '500123'
            campaign: example-value
            categoryId: 500123
            state: DRAFT
            currentState: active
            publishDate: '2025-03-15T14:30:00Z'
            created: '2025-03-15T14:30:00Z'
            updated: '2025-03-15T14:30:00Z'
            archivedAt: '2025-03-15T14:30:00Z'
            currentlyPublished: true
            domain: example.hubspot.com
            featuredImage: example-value
            featuredImageAltText: example-value
            metaDescription: This is an example description.
            headHtml: example-value
            footerHtml: example-value
            language: en
            translatedFromId: '500123'
            tagIds: *id001
            useFeaturedImage: true
            url: https://app.hubspot.com/contacts/12345
            abStatus: master
            abTestId: '500123'
            folderId: '500123'
        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
          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
          errors:
            type: array
            items:
              $ref: '#/components/schemas/StandardError'
            description: List of errors

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

    SetLanguagePrimaryRequest:
      type: object
      description: Request to set new primary language
      properties:
        id:
          type: string
          description: ID of the post to set as primary
          example: '500123'
      required:
      - id

    AttachToLanguageGroupRequest:
      type: object
      description: Request to attach to language group
      properties:
        id:
          type: string
          description: ID of the post to attach
          example: '500123'
        language:
          type: string
          description: Language code for the post
          example: en
        primaryId:
          type: string
          description: ID of the primary language post
          example: '500123'
        primaryLanguage:
          type: string
          description: Language code of the primary post
          example: en
      required:
      - id
      - language
      - primaryId

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

    Paging:
      type: object
      description: Pagination information
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'
        prev:
          $ref: '#/components/schemas/PagingPrevious'

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

          example: https://app.hubspot.com/contacts/12345
    PagingPrevious:
      type: object
      description: Pagination cursor for previous page
      properties:
        before:
          type: string
          description: Cursor token for the previous page
          example: example-value
        link:
          type: string
          description: API link to the previous page

          example: https://app.hubspot.com/contacts/12345
    StandardError:
      type: object
      description: Standard error in batch operations
      properties:
        status:
          type: string
          description: Error status
          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: Error message
          example: This is an example description.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          description: 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
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
      required:
      - status
      - category
      - message

    ErrorDetail:
      type: object
      description: Detailed error information
      properties:
        message:
          type: string
          description: Error message
          example: This is an example description.
        code:
          type: string
          description: Error code
          example: example-value
        subCategory:
          type: string
          description: Error subcategory
          example: standard
        in:
          type: string
          description: Location of error
          example: example-value
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example: &id002
            key: value
      required:
      - message

    Error:
      type: object
      description: Standard error response
      properties:
        category:
          type: string
          description: Error category
          example: standard
        correlationId:
          type: string
          format: uuid
          description: Unique tracking identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
          description: Error message
          example: This is an example description.
        subCategory:
          type: string
          description: Error subcategory
          example: standard
        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: This is an example description.
            code: example-value
            subCategory: standard
            in: example-value
            context: *id002
      required:
      - category
      - correlationId
      - message

  examples:
    BlogPostExample:
      summary: Complete blog post
      value:
        id: "123456789012"
        name: "How to Use HubSpot APIs"
        slug: "how-to-use-hubspot-apis"
        htmlTitle: "How to Use HubSpot APIs | Developer Guide"
        postBody: "<p>Learn how to integrate with HubSpot using our powerful APIs...</p>"
        postSummary: "A comprehensive guide to getting started with HubSpot APIs."
        blogAuthorId: "12345678901"
        authorName: "Jane Smith"
        contentGroupId: "9876543210"
        state: "PUBLISHED"
        publishDate: "2024-01-15T10:00:00Z"
        created: "2024-01-10T09:00:00Z"
        updated: "2024-01-15T10:00:00Z"
        currentlyPublished: true
        domain: "blog.example.com"
        featuredImage: "https://example.com/images/hubspot-apis.jpg"
        featuredImageAltText: "HubSpot API documentation"
        metaDescription: "Learn how to integrate with HubSpot using APIs"
        language: "en"
        tagIds: [101, 102, 103]
        useFeaturedImage: true
        url: "https://blog.example.com/how-to-use-hubspot-apis"

    BlogPostInputExample:
      summary: Blog post creation input
      value:
        name: "How to Use HubSpot APIs"
        slug: "how-to-use-hubspot-apis"
        htmlTitle: "How to Use HubSpot APIs | Developer Guide"
        postBody: "<p>Learn how to integrate with HubSpot using our powerful APIs...</p>"
        postSummary: "A comprehensive guide to getting started with HubSpot APIs."
        blogAuthorId: "12345678901"
        contentGroupId: "9876543210"
        featuredImage: "https://example.com/images/hubspot-apis.jpg"
        featuredImageAltText: "HubSpot API documentation"
        metaDescription: "Learn how to integrate with HubSpot using APIs"
        tagIds: [101, 102, 103]
        useFeaturedImage: true

    BlogPostCollectionExample:
      summary: Paginated list of blog posts
      value:
        total: 150
        results:
        - id: "123456789012"
          name: "How to Use HubSpot APIs"
          slug: "how-to-use-hubspot-apis"
          state: "PUBLISHED"
          publishDate: "2024-01-15T10:00:00Z"
          created: "2024-01-10T09:00:00Z"
          updated: "2024-01-15T10:00:00Z"
          currentlyPublished: true
        - id: "123456789013"
          name: "Getting Started with Webhooks"
          slug: "getting-started-with-webhooks"
          state: "DRAFT"
          created: "2024-01-12T14:00:00Z"
          updated: "2024-01-14T16:30:00Z"
          currentlyPublished: false
        paging:
          next:
            after: "NTI1Cg%3D%3D"
            link: "/cms/v3/blogs/posts?after=NTI1Cg%3D%3D"

    BatchResponseExample:
      summary: Successful batch operation
      value:
        status: "COMPLETE"
        results:
        - id: "123456789012"
          name: "How to Use HubSpot APIs"
          state: "PUBLISHED"
          created: "2024-01-10T09:00:00Z"
          updated: "2024-01-15T10:00:00Z"
        requestedAt: "2024-01-20T14:44:00Z"
        startedAt: "2024-01-20T14:44:01Z"
        completedAt: "2024-01-20T14:45:00Z"

    ErrorExample:
      summary: Validation error
      value:
        category: "VALIDATION_ERROR"
        correlationId: "aeb5f871-7f07-4993-9211-075dc63e7cbf"
        message: "Invalid input parameters"
        links:
          knowledge-base: "https://www.hubspot.com/products/service/knowledge-base"

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

paths:
  /cms/v3/blogs/posts:
    get:
      tags:
      - Blog Posts
      operationId: listBlogPosts
      summary: Hubspot List All Blog Posts
      description: |
        Retrieve a paginated list of all blog posts 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
        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 posts
        example: false
      - name: property
        in: query
        schema:
          type: string
        description: Specific property to return
        example: example-value
      responses:
        '200':
          description: Successfully retrieved blog posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPostCollection'
              examples:
                Success:
                  $ref: '#/components/examples/BlogPostCollectionExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    post:
      tags:
      - Blog Posts
      operationId: createBlogPost
      summary: Hubspot Create a Blog Post
      description: Create a new blog post in your HubSpot account.
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: |
          return "Success"
      security:
      - OAuth2:
        - content
      - PrivateApp: []
      requestBody:
        required: true
        description: Blog post data to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlogPostInput'
            examples:
              CreatePost:
                $ref: '#/components/examples/BlogPostInputExample'
      responses:
        '201':
          description: Successfully created blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPost'
              examples:
                Success:
                  $ref: '#/components/examples/BlogPostExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

  /cms/v3/blogs/posts/{objectId}:
    get:
      tags:
      - Blog Posts
      operationId: getBlogPostById
      summary: Hubspot Retrieve a Blog Post
      description: Retrieve a specific blog post by its 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 post
        example: "123456789012"
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to return archived posts
        example: false
      - name: property
        in: query
        schema:
          type: string
        description: Specific property to return
        example: example-value
      responses:
        '200':
          description: Successfully retrieved blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPost'
              examples:
                Success:
                  $ref: '#/components/examples/BlogPostExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    patch:
      tags:
      - Blog Posts
      operationId: updateBlogPost
      summary: Hubspot Update a Blog Post
      description: |
        Update an existing blog post. Only the properties included in the 
        request body will be updated.
      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 post
        example: "123456789012"
      - name: archived
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to update archived posts
        example: false
      requestBody:
        required: true
        description: Blog post properties to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlogPostInput'
            examples:
              UpdatePost:
                $ref: '#/components/examples/BlogPostInputExample'
      responses:
        '200':
          description: Successfully updated blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPost'
              examples:
                Success:
                  $ref: '#/components/examples/BlogPostExample'
        default:
          $ref: '#/components/responses/ErrorResponse'

    delete:
      tags:
      - Blog Posts
      operationId: archiveBlogPost
      summary: Hubspot Archive a Blog Post
      description: Archive (soft delete) a blog post by its 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 post
        example: "123456789012"
      responses:
        '204':
      

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