HubSpot Drafts and Revisions API

openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Drafts and Revisions 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: Drafts and Revisions
  description: Manage blog post drafts and revision history
paths:
  /cms/v3/blogs/posts/{objectId}/draft/push-live:
    post:
      tags:
      - Drafts and Revisions
      operationId: pushBlogPostDraftLive
      summary: Hubspot Push Draft to Live
      description: Push the draft version of a blog post to become the live version.
      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:
        '200':
          description: Successfully pushed draft to live
        default:
          $ref: '#/components/responses/ErrorResponse'
  /cms/v3/blogs/posts/{objectId}/draft/reset:
    post:
      tags:
      - Drafts and Revisions
      operationId: resetBlogPostDraft
      summary: Hubspot Reset Draft to Live Version
      description: Reset the draft version of a blog post to match the live version.
      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:
        '200':
          description: Successfully reset draft
        default:
          $ref: '#/components/responses/ErrorResponse'
  /cms/v3/blogs/posts/{objectId}/revisions:
    get:
      tags:
      - Drafts and Revisions
      operationId: getBlogPostRevisions
      summary: Hubspot Get Revision History
      description: Retrieve the revision history for a blog post.
      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: limit
        in: query
        schema:
          type: integer
          default: 20
        description: Maximum number of revisions to return
        example: 20
      - name: after
        in: query
        schema:
          type: string
        description: Pagination cursor
        example: example-value
      responses:
        '200':
          description: Successfully retrieved revisions
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/VersionHistory'
                  paging:
                    $ref: '#/components/schemas/Paging'
              examples:
                Getblogpostrevisions200Example:
                  summary: Default getBlogPostRevisions 200 response
                  x-microcks-default: true
                  value:
                    results:
                    - id: {}
                      object: {}
                      user: {}
                      timestamp: {}
                    paging:
                      next: {}
                      prev: {}
        default:
          $ref: '#/components/responses/ErrorResponse'
  /cms/v3/blogs/posts/{objectId}/revisions/{revisionId}/restore:
    post:
      tags:
      - Drafts and Revisions
      operationId: restoreBlogPostRevision
      summary: Hubspot Restore a Previous Version
      description: Restore a blog post to a previous version from its revision history.
      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: revisionId
        in: path
        required: true
        schema:
          type: string
        description: The revision ID to restore
        example: rev_123456
      responses:
        '200':
          description: Successfully restored revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlogPost'
              examples:
                Success:
                  $ref: '#/components/examples/BlogPostExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  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
    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: jsmith@example.com
            fullName: Example Record
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the version
          example: '2025-03-15T14:30:00Z'
    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
    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
  responses:
    ErrorResponse:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'
  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
    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
  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