HubSpot Posts API

openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Blog Posts 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: Blog Posts
  description: Create, read, update, and delete individual blog posts
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. \nUse query parameters to filter, sort, and paginate the results.\n"
      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 \nrequest body will be updated.\n"
      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':
          description: Successfully archived blog post
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  examples:
    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
    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
    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
    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
  schemas:
    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:
            key: value
      required:
      - message
    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:
          - 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
    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
    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:
              key: value
      required:
      - category
      - correlationId
      - message
    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:
            - 500123
            useFeaturedImage: true
            url: https://app.hubspot.com/contacts/12345
            abStatus: master
            abTestId: '500123'
            folderId: '500123'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - total
      - results
    Paging:
      type: object
      description: Pagination information
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'
        prev:
          $ref: '#/components/schemas/PagingPrevious'
    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
    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
  responses:
    ErrorResponse:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'
  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