openapi: 3.0.2
info:
  title: Help Center API
  description: Help Center v2 REST API
  version: 2.0.0
tags:
  - name: Articles
  - name: Article Labels
  - name: Article Attachments
  - name: Translations
  - name: Categories
  - name: Sections
  - name: Sessions
  - name: Votes
  - name: User Segments
  - name: Article Comments
  - name: Search
  - name: Topics
  - name: Posts
  - name: Post Comments
  - name: Content Subscriptions
  - name: User Subscriptions
  - name: User Images
paths:
  /api/v2/community/posts:
    get:
      operationId: ListPosts
      tags:
        - Posts
      summary: List Posts
      parameters:
        - name: filter_by
          in: query
          description: Filter the results using the provided value
          schema:
            type: string
            enum:
              - planned
              - not_planned
              - completed
              - answered
              - none
        - name: sort_by
          in: query
          description: Sorts the results using the provided value
          schema:
            type: string
            enum:
              - created_at
              - edited_at
              - updated_at
              - recent_activity
              - votes
              - comments
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostsResponseExample'
    post:
      operationId: CreatePost
      tags:
        - Posts
      summary: Create Post
      description: |
        Adds a post to the specified [topic](/api-reference/help_center/help-center-api/topics).

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply an
        `author_id` as part of the `post` object. If it is provided, the post's
        author will be set to the value of the `author_id` key.

        Agents with the Help Center manager role can optionally supply a `created_at` as part of the `post` object. If it is not provided `created_at` is set to the current time.

        Supplying a `notify_subscribers` property with a value of false will prevent subscribers to the post's topic from receiving a post creation email notification. This can be helpful when creating many posts at a time. Specify the property in the root of the JSON object, not in the "post" object.
        Optionally, you can attach existing [content tags](/api-reference/help_center/help-center-api/content_tags) by specifying their ids.
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created article attachment
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/community/posts.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostResponseExample'
  /api/v2/community/posts/{post_id}:
    parameters:
      - $ref: '#/components/parameters/PostId'
    get:
      operationId: ShowPost
      tags:
        - Posts
      summary: Show Post
      description: |
        Gets information about a given post.

        #### Allowed for

        * Anonymous users

        #### Sideloads
        The following sideloads are supported:

        | Name        | Will sideload
        |-------------|--------------
        | users       | authors
        | topics      | topics
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostResponseExample'
    put:
      operationId: UpdatePost
      tags:
        - Posts
      summary: Update Post
      description: |
        #### Allowed for

        * Agents
        * The end user who created the post
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostResponseExample'
    delete:
      operationId: DeletePost
      tags:
        - Posts
      summary: Delete Post
      description: |
        #### Allowed for

        * Agents
        * The end user who created the post
      responses:
        "204":
          description: Default success response
  /api/v2/community/posts/{post_id}/comments:
    parameters:
      - $ref: '#/components/parameters/PostId'
    get:
      operationId: ListPostComments
      tags:
        - Post Comments
      summary: List Comments
      description: |
        Lists all comments on a specific post or all the comments created by a specific user.
        When listing comments by specific user, the comments of the user making the request
        can be listed by specifying `me` as the id.

        #### Allowed for

        * End users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads

        You can sideload related records with the `include` query string parameter. The following sideloads are supported:

        | Name   | Will sideload
        |--------|--------------
        | users  | authors
        | posts  | posts

        See [Sideloading related records](/documentation/developer-tools/working-with-data/sideloading-related-records).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCommentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostCommentsResponseExample'
    post:
      operationId: CreatePostComment
      tags:
        - Post Comments
      summary: Create Post Comment
      description: |
        Adds a comment to the specified post.

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply an
        `author_id` as part of the `comment` object. If it is provided, the
        comment's author will be set to the value of the `author_id` key.

        Supplying a `notify_subscribers` property with a value of false
        will prevent subscribers to the comment's post from receiving a comment
        creation email notification. This can be helpful when creating many
        comments at a time. Specify the property in the root of the JSON object, not in the "comment" object.
      responses:
        "201":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostCommentResponseExample'
  /api/v2/community/posts/{post_id}/comments/{post_comment_id}:
    parameters:
      - $ref: '#/components/parameters/PostId'
      - $ref: '#/components/parameters/PostCommentId'
    get:
      operationId: ShowPostComment
      tags:
        - Post Comments
      summary: Show Comment
      description: |
        Shows information about the specified comment.

        #### Allowed for

        * End users

        #### Sideloads

        The following sideloads are supported:

        | Name   | Will sideload
        |--------|--------------
        | users  | The comment's author
        | posts  | The comment's post
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostCommentResponseExample'
    put:
      operationId: UpdatePostComment
      tags:
        - Post Comments
      summary: Update Comment
      description: |
        Updates the specified comment.

        #### Allowed for

        * Agents
        * The end user who created the comment
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostCommentResponseExample'
    delete:
      operationId: DeletePostComment
      tags:
        - Post Comments
      summary: Delete Comment
      description: |
        Deletes the specified comment.

        #### Allowed for

        * Agents
        * The end user who created the comment
      responses:
        "204":
          description: Default success response
  /api/v2/community/posts/{post_id}/subscriptions:
    parameters:
      - $ref: '#/components/parameters/PostId'
    get:
      operationId: ListPostSubscriptions
      tags:
        - Content Subscriptions
      summary: List Post Subscriptions
      description: |
        Lists the subscriptions to a given post.

        #### Allowed for

        * End users

        For end-users, the response will list only the subscriptions created by the
        requesting end-user.

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | users
        | posts         | posts
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostSubscriptionsResponseExample'
    post:
      operationId: CreatePostSubscription
      tags:
        - Content Subscriptions
      summary: Create Post Subscription
      description: |
        Creates a subscription to a given [post](/api-reference/help_center/help-center-api/posts).

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply a
        `subscription` object containing a `user_id` value. If provided,
        the user associated with `user_id` will be subscrbed to the post.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created subscription
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{subscription_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostSubscriptionResponseExample'
  /api/v2/community/posts/{post_id}/subscriptions/{subscription_id}:
    parameters:
      - $ref: '#/components/parameters/PostId'
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: ShowPostSubscription
      tags:
        - Content Subscriptions
      summary: Show Post Subscription
      description: |
        #### Allowed for

        * End users

        For end users, the response will only show a subscription created by the requesting end user.

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
        | posts         | posts         | post subscriptions
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/PostSubscriptionResponseExample'
    delete:
      operationId: DeletePostSubscription
      tags:
        - Content Subscriptions
      summary: Delete Post Subscription
      description: |
        Removes a subscription to a given [post](/api-reference/help_center/help-center-api/posts).

        #### Allowed for

        * End-users
      responses:
        "204":
          description: Default success response
  /api/v2/community/topics:
    get:
      operationId: ListTopics
      tags:
        - Topics
      summary: List Topics
      description: |
        Lists all topics.

        #### Allowed for

        * Anonymous users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicsResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicsResponseExample'
    post:
      operationId: CreateTopic
      tags:
        - Topics
      summary: Create Topic
      description: |
        #### Allowed for

        * Help Center managers

        Agents with the Help Center Manager role can optionally supply a `created_at` as part of the `topic` object. If it is not provided `created_at` is set to the current time.
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created topic
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/community/topics.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicResponseExample'
  /api/v2/community/topics/{topic_id}:
    parameters:
      - $ref: '#/components/parameters/TopicId'
    get:
      operationId: ShowTopic
      tags:
        - Topics
      summary: Show Topic
      description: |
        Shows information about a single topic.

        #### Allowed for

        * Anonymous users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicResponseExample'
    put:
      operationId: UpdateTopic
      tags:
        - Topics
      summary: Update Topic
      description: |
        #### Allowed for

        * Help Center managers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicResponseExample'
    delete:
      operationId: DeleteTopic
      tags:
        - Topics
      summary: Delete Topic
      description: |
        #### Allowed for

        * Help Center managers
      responses:
        "204":
          description: Default success response
  /api/v2/community/topics/{topic_id}/subscriptions:
    parameters:
      - $ref: '#/components/parameters/TopicId'
    get:
      operationId: ListTopicSubscriptions
      tags:
        - Content Subscriptions
      summary: List Topic Subscriptions
      description: |
        Lists the subscriptions to a given topic.

        #### Allowed for

        * End users

        For end users, the response will list only the subscriptions created by the
        requesting end user.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | users
        | topics        | topics
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicSubscriptionsResponseExample'
    post:
      operationId: CreateTopicSubscription
      tags:
        - Content Subscriptions
      summary: Create Topic Subscription
      description: |
        Creates a subscription to a given [topic](/api-reference/help_center/help-center-api/topics).

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply a `user_id`
        value. If provided, the user associated with `user_id` will be subscribed
        to the topic.
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created subscription
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{subscription_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicSubscriptionResponseExample'
  /api/v2/community/topics/{topic_id}/subscriptions/{subscription_id}:
    parameters:
      - $ref: '#/components/parameters/TopicId'
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: ShowTopicSubscription
      tags:
        - Content Subscriptions
      summary: Show Topic Subscription
      description: |
        #### Allowed for

        * End users

        For end users, the response will only show a subscription created by the requesting end user.

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
        | topics        | topics        | topic subscriptions
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicSubscriptionResponseExample'
    put:
      operationId: UpdateTopicSubscription
      tags:
        - Content Subscriptions
      summary: Update Topic Subscription
      description: |
        #### Allowed for

        * End users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/TopicSubscriptionResponseExample'
    delete:
      operationId: DeleteTopicSubscription
      tags:
        - Content Subscriptions
      summary: Delete Topic Subscription
      description: |
        Removes a subscription to a given [topic](/api-reference/help_center/help-center-api/topics).

        #### Allowed for

        * End users
      responses:
        "204":
          description: Default success response
  /api/v2/guide/search:
    get:
      operationId: UnifiedSearch
      tags:
        - Search
      summary: Unified Search
      parameters:
        - name: query
          in: query
          description: |
            The search text to be matched or a search string
          schema:
            type: string
          example: carrot
        - name: filter[locales]
          in: query
          description: Limit the search to these locales. See [Filtering by Locale](#filtering-by-locale)
          required: true
          schema:
            type: string
          example: en-us,en-gb
        - name: filter[category_ids]
          in: query
          description: Limit the search to articles in these categories. See [Filtering by Category](#filtering-by-category)
          schema:
            type: string
          example: 42,43
        - name: filter[section_ids]
          in: query
          description: Limit the search to articles in these sections. See [Filtering by Section](#filtering-by-section)
          schema:
            type: string
          example: 42,43
        - name: filter[topic_ids]
          in: query
          description: Limit the search to posts in these topics. See [Filtering by Topic](#filtering-by-topic)
          schema:
            type: string
          example: 42,43
        - name: filter[external_source_ids]
          in: query
          description: "Use this parameter to scope the result of your search to a specific external source or external sources. \nIf no external source is given, results are returned across all sources\n"
          schema:
            type: string
          example: 01EC05A5T1J4ZSDJX4Q8JGFRHP
        - name: filter[brand_ids]
          in: query
          description: "Limit the search to articles or posts within these brands. If no brand is specified, results are returned across all brands. \nIf you want to scope the result of your search with multiple brands, separate each value with a comma\n"
          schema:
            type: string
            items:
              type: string
          example: 73,67
        - name: filter[content_types]
          in: query
          description: "Limit the search to one of these content types: ARTICLE, POST. \nAt present, it is not possible to specify `EXTERNAL_RECORD`. \nInstead, use the `filter[external_source_id]` parameter above\n"
          schema:
            type: string
          example: ARTICLE,POST
        - name: page[after]
          in: query
          description: |
            A string representing the cursor to the next page.
          schema:
            type: string
        - name: page[size]
          in: query
          description: |
            A numeric value that indicates the maximum number of items that can
            be included in a response. The value of this parameter has an upper
            limit of 50. The default value is 10.
          schema:
            type: integer
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedSearchResultSet'
              examples:
                default:
                  $ref: '#/components/examples/UnifiedSearchResponseExample'
  /api/v2/guide/user_images:
    post:
      operationId: CreateUserImage
      tags:
        - User Images
      summary: Create Image Path
      description: |
        Returns the image path that you can use to display the image in a community post.

        You should only use this endpoint after uploading the image. See [Uploading the image with the upload URL](#uploading-the-image-with-the-upload-url).

        #### Request Body Format
        The request body must be a JSON object with the following properties:

        | Name         | Type   | Mandatory | Description |
        | ------------ | ------ | --------- | ----------- |
        | token        | string | true      | The image token. See [Create Image Upload URL and Token](#create-image-upload-url-and-token) |
        | brand_id     | string | true      | The ID of the brand where this image was uploaded |

        #### Allowed for

        * Anonymous users
      responses:
        "201":
          description: Created Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserImageResponse'
              examples:
                default:
                  $ref: '#/components/examples/CreateuserImageResponseExample'
  /api/v2/guide/user_images/uploads:
    post:
      operationId: RequestUserImageUpload
      tags:
        - User Images
      summary: Create Image Upload URL and Token
      description: |
        Returns an upload URL and token. Use the upload URL in a PUT request to upload the image to the help center. See [Uploading the image with the upload URL](#uploading-the-image-with-the-upload-url) below.

        After uploading the image, use the image token to create the image path. See [Create Image Path](#create-image-path).

        #### Uploading the image with the upload URL

        The endpoint returns an object with the `url` and `headers` properties:

        ```json
        "headers": {
          "Content-Disposition": "attachment; filename=\"01GC9JEN2X052BAKW905PH9C36.jpeg\"",
          "Content-Type": "image/jpeg",
          "X-Amz-Server-Side-Encryption": "AES256"
        },
        ...
        "url": "https://aus-uploaded-assets-production.s3-accelerate.amazonaws.com/20/13633840/01GC9JEN2X052BAKW905PH9C36?Content-Type=image%2Fjpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ACCESS_KEY%2F20220906%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220906T141448Z&X-Amz-Expires=3600&X-Amz-Signature=476f8f09a97cae0bb582716d54dc58cdfbc754c5e20a2c492515d7ffce954971&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256"
        ```

        To upload the image, make a PUT request to the URL and with the specified headers. Agents, end users, or anonymous users can make the request. The maximum file size is 2MB.

        The following curl example uploads the image:

        ```sh
        curl -L -X PUT 'https://aus-uploaded-assets-production.s3-accelerate.amazonaws.com/20/13633840/01GC9JEN2X052BAKW905PH9C36?Content-Type=image%2Fjpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ACCESS_KEY%2F20220906%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220906T141448Z&X-Amz-Expires=3600&X-Amz-Signature=476f8f09a97cae0bb582716d54dc58cdfbc754c5e20a2c492515d7ffce954971&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256' \
          -H 'Content-Disposition: attachment; filename="01GC9JEN2X052BAKW905PH9C36.jpeg"' \
          -H 'Content-Type: image/jpeg' \
          -H 'X-Amz-Server-Side-Encryption: AES256' \
          --data-binary "@{file}"
        ```

        A successful response will return:

        ```
        Status 200 OK
        ```

        #### Request Body Format
        The request body of `POST /api/v2/guide/user_images/uploads` must be a JSON object with the following properties:

        | Name         | Type   | Mandatory | Description |
        | ------------ | ------ | --------- | ----------- |
        | content_type | string | true      | The content type of the file to upload |
        | file_size    | number | true      | Size of the file in bytes. Max size is 2000000 (2MB). |

        #### Allowed for

        * Anonymous users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestUserImageUploadResponse'
              examples:
                default:
                  $ref: '#/components/examples/RequestUserImageUploadResponseExample'
  /api/v2/help_center/{locale}/articles:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
    get:
      operationId: ListArticles
      tags:
        - Articles
      summary: List Articles
      parameters:
        - name: sort_by
          in: query
          description: Sorts the articles by one of the accepted values
          schema:
            type: string
            enum:
              - position
              - title
              - created_at
              - updated_at
        - name: sort_order
          in: query
          description: Selects the order of the results.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: start_time
          in: query
          description: You can use the incremental article endpoint to list all the articles that were updated since a certain date and time.
          schema:
            type: integer
          example: 1404345231
        - name: label_names
          in: query
          description: Only articles that have all the labels are returned.
          schema:
            type: string
          example: photos,camera
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticlesResponseExample'
  /api/v2/help_center/{locale}/articles/{article_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ShowArticle
      tags:
        - Articles
      summary: Show Article
      description: |
        Shows the properties of an article.

        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * Anonymous users

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | the author
        | sections      | the section
        | categories    | the category
        | translations  | the article, section and category translations, if any

        Unlike other sideloads, translations are embedded within the article because they're
        not shared between resources.
        Section and category translations are only sideloaded if present.
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleResponseExample'
    put:
      operationId: UpdateArticle
      tags:
        - Articles
      summary: Update Article
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleResponseExample'
    delete:
      operationId: ArchiveArticle
      tags:
        - Articles
      summary: Archive Article
      description: |
        Archives the article. You can restore the article using the Help Center user interface. See [Viewing and restoring archived articles](https://support.zendesk.com/hc/en-us/articles/235721587).

        #### Allowed for

        * Agents
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/{locale}/articles/{article_id}/bulk_attachments:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    post:
      operationId: BulkAttachmentsArticles
      tags:
        - Articles
      summary: Associate Attachments in Bulk to Article
      description: |
        You can associate attachments in bulk to only one article at a time,
        with a maximum of 20 attachments per request.

        To create the attachments, see [Create Unassociated Attachment](/api-reference/help_center/help-center-api/article_attachments#create-unassociated-attachment).

        #### Allowed for

        * Agents
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                type: string
                description: Empty response
                example: ""
              example: ""
  /api/v2/help_center/{locale}/articles/{article_id}/comments:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListArticleComments
      tags:
        - Article Comments
      summary: List Comments
      description: |
        Lists the comments created by a specific user, or all comments made by all users on
        a specific article.

        The `{locale}` for the article comments is required only for end users. Admins and agents can omit it.

        #### Allowed for

        * End users

        End-users can only list their own comments. If listing comments by user, they must specify `me` as the id.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | authors
        | articles      | articles
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/CommentsResponseExample'
    post:
      operationId: CreateArticleComment
      tags:
        - Article Comments
      summary: Create Comment
      description: |
        Adds a comment to the specified [article](/api-reference/help_center/help-center-api/articles). Because comments are associated
        with a specific article translation, or locale, you must specify a locale.

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply a `created_at` as part of the `comment` object. If not provided, `created_at` is set to the current time.

        Supplying a `notify_subscribers` property with a value of false will prevent subscribers to the comment's article from receiving a comment creation email notification. This can be helpful when creating many comments at a time. Specify the property in the root of the JSON object, not in the "comment" object.
      responses:
        "200":
          description: description
          headers:
            Location:
              description: The URL of the new created comment
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/comments/{comment_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/CommentResponseExample'
  /api/v2/help_center/{locale}/articles/{article_id}/comments/{comment_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
      - $ref: '#/components/parameters/CommentId'
    get:
      operationId: ShowComment
      tags:
        - Article Comments
      summary: Show Comment
      description: |
        Shows the properties of the specified comment.

        The `{locale}` is required only for end users and anomynous users. Admins and agents can omit it.

        #### Allowed for

        * Anonymous users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/CommentResponseExample'
    put:
      operationId: UpdateComment
      tags:
        - Article Comments
      summary: Update Comment
      description: |
        #### Allowed for

        * Agents
        * The end user who created the comment
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
              examples:
                default:
                  $ref: '#/components/examples/CommentResponseExample'
    delete:
      operationId: DeleteComment
      tags:
        - Article Comments
      summary: Delete Comment
      description: |
        #### Allowed for

        * Agents
        * The end user who created the comment
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/{locale}/articles/{article_id}/labels:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListArticleLabels
      tags:
        - Article Labels
      summary: List Article Labels
      description: |
        Lists all the labels in a given article.

        #### Allowed for

        * Agents

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleLabelsResponseExample'
    post:
      operationId: CreateArticleLabel
      tags:
        - Article Labels
      summary: Create Label
      description: |
        #### Allowed for

        * Agents
      responses:
        "201":
          description: Created Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleLabelResponseExample'
  /api/v2/help_center/{locale}/articles/{article_id}/labels/{label_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
      - $ref: '#/components/parameters/LabelId'
    delete:
      operationId: DeleteArticleLabel
      tags:
        - Article Labels
      summary: Delete Label from Article
      description: |
        Removes the label from the specified article's list of labels.

        #### Allowed for

        * Agents
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/{locale}/articles/{article_id}/source_locale:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    put:
      operationId: UpdateArticleSourceLocale
      tags:
        - Articles
      summary: Update Article Source Locale
      description: |
        Updates the article's `source_locale` property. The source locale is the main language of the article. When you delete the article in the source locale, you delete all the article's translations.

        The endpoint sets one of the article's translation as the source locale of the article. The article in the previous source locale becomes a translation, which you can delete separately.

        The new source locale must be enabled in Guide. See [Enabling languages for your help center](https://support.zendesk.com/hc/en-us/articles/224857687#topic_ys2_kxh_tz). You can use the [List all enabled locales and default locale](/api-reference/help_center/help-center-api/translations/#list-enabled-locales-and-default-locale) endpoint to check for the enabled locales.

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                type: string
                description: Empty response
                example: ""
              example: ""
  /api/v2/help_center/{locale}/articles/{article_id}/subscriptions:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListArticleSubscriptions
      tags:
        - Content Subscriptions
      summary: List Article Subscriptions
      description: |
        Lists the subscriptions to a given article.

        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * End users

        For end-users, the response will list only the subscriptions created by the
        requesting end-user.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | users
        | articles      | articles
        | sections      | sections

        Note that you need to specify the `articles` sideload to get the sections
        and translations sideloaded because these are not directly associated with the
        subscriptions.
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleSubscriptionsResponseExample'
    post:
      operationId: CreateArticleSubscription
      tags:
        - Content Subscriptions
      summary: Create Article Subscription
      description: |
        Creates a subscription to a given [article](/api-reference/help_center/help-center-api/articles).

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply a `user_id`
        value. If provided, the user associated with `user_id` will be subscribed
        to the article.
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created subscription
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{subscription_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleSubscriptionResponseExample'
  /api/v2/help_center/{locale}/articles/{article_id}/subscriptions/{subscription_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: ShowArticleSubscription
      tags:
        - Content Subscriptions
      summary: Show Article Subscription
      description: |
        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * End users

        For end-users, the response will only show a subscription created by the requesting end-user.

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
        | articles      | articles      | article subscriptions
        | sections      | sections      | section subscriptions
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleSubscriptionResponseExample'
    delete:
      operationId: DeleteArticleSubscription
      tags:
        - Content Subscriptions
      summary: Delete Article Subscription
      description: |
        Removes the specified subscription from the specified [article](/api-reference/help_center/help-center-api/articles).

        #### Allowed for

        * End users
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/{locale}/articles/{article_id}/up:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/ArticleId'
    post:
      operationId: CreateArticleUpVote
      tags:
        - Votes
      summary: Create Vote
      description: |
        Creates an up or down vote for a given [article](/api-reference/help_center/help-center-api/articles), [article comment](/api-reference/help_center/help-center-api/article_comments/), [post](/api-reference/help_center/help-center-api/posts), or [post comment](/api-reference/help_center/help-center-api/post_comments).
        If a vote already exists for the source object, it's updated.

        #### Allowed for

        * End users
      responses:
        "200":
          description: OK Response
          headers:
            Location:
              description: The URL of the new created vote
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/votes/{vote_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleUpVoteResponseExample'
  /api/v2/help_center/{locale}/categories:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
    get:
      operationId: ListCategories
      tags:
        - Categories
      summary: List Categories
      description: |
        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * Anonymous users

        The response will list only the categories that the agent, end user, or
        anonymous user can view in the help center.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sorting

        You can sort the results with the `sort_by` and `sort_order` query string parameters.

        ```
        GET /api/v2/help_center/en-us/categories.json?sort_by=updated_at&sort_order=asc
        ```

        The `sort_by` parameter can have one of the following values:

        | value         | description
        | ------------- | -----------
        | `position`    | order set manually using the Arrange Content page. Default order
        | `created_at`  | order by creation time
        | `updated_at`  | order by update time

        The `sort_order` parameter can have one of the following values:

        | value   | description
        | ------- | -----------
        | `asc`   | ascending order
        | `desc`  | descending order

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | translations  | the category translations, if any

        Translations are embedded within the category because they're
        not shared between resources.
      parameters:
        - name: sort_by
          in: query
          description: Sorts the results by one of the accepted values
          schema:
            type: string
            enum:
              - position
              - created_at
              - updated_at
        - name: sort_order
          in: query
          description: Selects the order of the results.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoriesResponse'
              examples:
                default:
                  $ref: '#/components/examples/CategoriesResponseExample'
    post:
      operationId: CreateCategory
      tags:
        - Categories
      summary: Create Category
      description: |
        You must specify a category name and locale. The locale can be omitted if it's specified
        in the URL. Optionally, you can specify multiple [translations](/api-reference/help_center/help-center-api/translations) for
        the category. The specified locales must be enabled for the current Help Center.

        #### Allowed for

        * Help Center managers
      responses:
        "201":
          description: OK Response
          headers:
            Location:
              description: The URL of the new created category
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/categories/{category_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                default:
                  $ref: '#/components/examples/CategoryResponseExample'
  /api/v2/help_center/{locale}/categories/{category_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/CategoryId'
    get:
      operationId: ShowCategory
      tags:
        - Categories
      summary: Show Category
      description: |
        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * Anonymous users

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | translations  | the category translations, if any

        Translations are embedded within the category because they're
        not shared between resources.
      responses:
        "200":
          description: description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                default:
                  $ref: '#/components/examples/CategoryResponseExample'
    put:
      operationId: UpdateCategory
      tags:
        - Categories
      summary: Update Category
      description: |
        These endpoints only update category-level metadata such as the sorting position.
        They don't update category translations.

        #### Allowed for

        * Help Center managers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                default:
                  $ref: '#/components/examples/CategoryResponseExample'
    delete:
      operationId: DeleteCategory
      tags:
        - Categories
      summary: Delete Category
      description: |
        **WARNING: Every section and all articles in the category will also be deleted.**

        #### Allowed for

        * Help Center managers
      responses:
        "204":
          description: No content
  /api/v2/help_center/{locale}/categories/{category_id}/sections:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/CategoryId'
    post:
      operationId: CreateSection
      tags:
        - Sections
      summary: Create Section
      description: |
        Creates a section in a given [category](/api-reference/help_center/help-center-api/categories). You must
        specify a section name and locale. The locale can be omitted if it's specified
        in the URL. Optionally, you can specify multiple [translations](/api-reference/help_center/help-center-api/translations)
        for the section. The specified locales must be enabled for
        the current Help Center.

        #### Allowed for

        * Agents
      responses:
        "201":
          description: description
          headers:
            Location:
              description: The URL of the new created section
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/sections/{section_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionResponseExample'
        "400":
          description: Bad request Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                default:
                  $ref: '#/components/examples/BadRequestCreateSection'
  /api/v2/help_center/{locale}/categories/{category_id}/source_locale:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/CategoryId'
    put:
      operationId: UpdateCategorySourceLocale
      tags:
        - Categories
      summary: Update Category Source Locale
      description: |
        The endpoint updates the category `source_locale` property

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                type: string
                description: Empty response
                example: ""
              example: ""
  /api/v2/help_center/{locale}/sections:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
    get:
      operationId: ListSections
      tags:
        - Sections
      summary: List Sections
      description: |
        Lists all the sections in Help Center or in a specific [category](/api-reference/help_center/help-center-api/categories).

        The `{locale}` is required only for end users and anomynous users. Admins and agents can omit it.

        #### Allowed for

        * Anonymous users

        The response will list only the sections that the requesting agent,
        end user, or anonymous user can view in the help center.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sorting

        You can sort the results with the `sort_by` and `sort_order` query string parameters.

        ```
        GET /api/v2/help_center/en-us/sections.json?sort_by=updated_at&sort_order=asc
        ```

        The `sort_by` parameter can have one of the following values:

        | value         | description
        | ------------- | -----------
        | `position`    | order set manually using the Arrange Content page. Default order
        | `created_at`  | order by creation time
        | `updated_at`  | order by update time

        The `sort_order` parameter can have one of the following values:

        | value   | description
        | ------- | -----------
        | `asc`   | ascending order
        | `desc`  | descending order

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | categories    | the category
        | translations  | the section and category translations, if any

        Unlike other sideloads, translations are embedded within the section because they're
        not shared between resources.
        Category translations are only sideloaded if categories are.
      parameters:
        - name: sort_by
          in: query
          description: Sorts the results by one of the accepted values
          schema:
            type: string
            enum:
              - position
              - created_at
              - updated_at
        - name: sort_order
          in: query
          description: Selects the order of the results.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionsResponseExample'
  /api/v2/help_center/{locale}/sections/{section_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/SectionId'
    get:
      operationId: ShowSection
      tags:
        - Sections
      summary: Show Section
      description: |
        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * Anonymous users

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | categories    | the category
        | translations  | the section and category translations, if any

        Unlike other sideloads, translations are embedded within the section since they're
        not shared between resources.
        [Category](/api-reference/help_center/help-center-api/categories) translations are only sideloaded if categories are.
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionResponseExample'
    put:
      operationId: UpdateSection
      tags:
        - Sections
      summary: Update Section
      description: |
        Update section. This endpoint updates section-level data, specifically:

        * name (in the source locale)
        * description (in the source locale)
        * position
        * sorting
        * category_id
        * parent_section_id
        * theme_template

        To update non-source section translations, see [Translations](/api-reference/help_center/help-center-api/translations).

        #### Allowed for

        * Help Center managers
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SectionPutRequest'
            examples:
              default:
                value:
                  section:
                    position: 3
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionResponseExample'
        "400":
          description: Bad request Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                default:
                  $ref: '#/components/examples/BadRequestUpdateSection'
    delete:
      operationId: DeleteSection
      tags:
        - Sections
      summary: Delete Section
      description: |
        **WARNING: All articles in the section will also be deleted.**

        #### Allowed for

        * Help Center managers
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/{locale}/sections/{section_id}/articles:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/SectionId'
    post:
      operationId: CreateArticle
      tags:
        - Articles
      summary: Create Article
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleRequest'
            examples:
              default:
                $ref: '#/components/examples/ArticleRequestExample'
      responses:
        "201":
          description: OK Response
          headers:
            Location:
              description: The URL of the new created article
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleResponseExample'
  /api/v2/help_center/{locale}/sections/{section_id}/source_locale:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/SectionId'
    put:
      operationId: UpdateSectionSourceLocale
      tags:
        - Sections
      summary: Update Section Source Locale
      description: |
        This endpoint lets you set a section's source language to something other
        than the default language of your Help Center. For example, if the default language
        of your Help Center is English but your KB has a section only for Japanese customers,
        you can set the section's source locale to 'ja'.

        #### Allowed for

        * Help Center managers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                type: string
                description: Empty response
                example: ""
              example: ""
  /api/v2/help_center/{locale}/sections/{section_id}/subscriptions:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/SectionId'
    get:
      operationId: ListSectionSubscriptions
      tags:
        - Content Subscriptions
      summary: List Section Subscriptions
      description: |
        Lists the subscriptions to a given [section](/api-reference/help_center/help-center-api/sections).

        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * End users

        For end-users, the response will list only the subscriptions created by the
        requesting end-user.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | users
        | sections      | sections
        | translations  | translations of any sideloaded articles and sections

        To sideload the section translations, specify the `translations` sideload in
        addition to `sections`.
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionSubscriptionsResponseExample'
    post:
      operationId: CreateSectionSubscription
      tags:
        - Content Subscriptions
      summary: Create Section Subscription
      description: |
        Creates a subscription to a given [section](/api-reference/help_center/help-center-api/sections).

        #### Allowed for

        * End users

        Agents with the Help Center manager role can optionally supply a `user_id`
        value. If provided, the user associated with `user_id` will be subscribed
        to the section.
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created subscription
              schema:
                type: string
              example: https://{subdomain}.zendesk.com/api/v2/help_center/subscriptions/{subscription_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionSubscriptionResponseExample'
  /api/v2/help_center/{locale}/sections/{section_id}/subscriptions/{subscription_id}:
    parameters:
      - $ref: '#/components/parameters/OptionalLocale'
      - $ref: '#/components/parameters/SectionId'
      - $ref: '#/components/parameters/SubscriptionId'
    get:
      operationId: ShowSectionSubscription
      tags:
        - Content Subscriptions
      summary: Show Section Subscription
      description: |
        **Note**: `{/locale}` is an optional parameter for admins and agents. End users and anonymous users must provide the parameter.

        #### Allowed for

        * End users

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
        | sections      | sections      | section subscriptions
        | translations  | translations  | article or section subscriptions
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SectionSubscriptionResponseExample'
    delete:
      operationId: DeleteSectionSubscription
      tags:
        - Content Subscriptions
      summary: Delete Section Subscription
      description: |
        Removes the specified subscription from the specified [section](/api-reference/help_center/help-center-api/sections).

        #### Allowed for

        * End users
      responses:
        "204":
          description: delete body
  /api/v2/help_center/articles/{article_id}/attachments:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListArticleAttachments
      tags:
        - Article Attachments
      summary: List Article Attachments
      description: |
        Lists all the article's attachments.

        **Note**: By default the pagination returns the maximum attachments per page, which is 100.

        #### Allowed for

         * Agents
         * End users, as long as they can view the associated article

        #### Pagination
          * Cursor pagination (recommended)
          * Offset pagination

          See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleAttachmentsResponseExample'
    post:
      operationId: CreateArticleAttachment
      tags:
        - Article Attachments
      summary: Create Article Attachment
      description: |
        Creates an attachment for the specified [article](/api-reference/help_center/help-center-api/articles). You can specify whether the
        attachment is `inline` or not. The default is false.

        If your integration depends on keeping the translation body in sync with an external system, create a separate article attachment for each translation and set the locale in advance.
        Inline article attachments are automatically assigned a locale when they are embedded in a translation body. If the same attachment is inserted in multiple translations, it will create multiple article attachment records, all linked to the same file, and the references in the translation bodies will be updated accordingly.

        *Notes:*

          - While it is possible to provide a file as a parameter, it is however recommended to first create a [guide-media](/api-reference/help_center/guide_medias) and then create an article attachment by providing a guide_media_id.
          - Inline article attachments that are no longer embedded in the translation get deleted. However the corresponding file is kept in guide-medias

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK Response
          headers:
            Location:
              description: The URL of the new created article attachment
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/articles/{article_id}/attachments.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleAttachmentResponseExample'
  /api/v2/help_center/articles/{article_id}/attachments/{article_attachment_id}:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
      - $ref: '#/components/parameters/ArticleAttachmentId'
    get:
      operationId: ShowArticleAttachment
      tags:
        - Article Attachments
      summary: Show Article Attachment
      description: |
        Shows the properties of the specified attachment.

        **Note**: Omit `{/article_id}` to access unassociated article attachments.

        #### Allowed for

        * Agents
        * End users, as long as they can view the associated article
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleAttachmentResponseExample'
  /api/v2/help_center/articles/{article_id}/attachments/block:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListBlockArticleAttachments
      tags:
        - Article Attachments
      summary: List Article Block Attachments
      description: |
        Lists all the article's block attachments. Block attachments are those that are not inline.

        #### Allowed for

        * Agents
        * End users, as long as they can view the associated article
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/BlockArticleAttachmentsResponseExample'
  /api/v2/help_center/articles/{article_id}/attachments/inline:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListInlineArticleAttachments
      tags:
        - Article Attachments
      summary: List Article Inline Attachments
      description: |
        Lists all the article's inline attachments.

        #### Allowed for

        * Agents
        * End users, as long as they can view the associated article
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/InlineArticleAttachmentsResponseExample'
  /api/v2/help_center/articles/{article_id}/translations:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListTranslations
      tags:
        - Translations
      summary: List Translations
      description: |
        Lists all translations for a given [article](/api-reference/help_center/help-center-api/articles), [section](/api-reference/help_center/help-center-api/sections), or [category](/api-reference/help_center/help-center-api/categories).

        #### Allowed for

        * End users

        For end users, the response will list only the translations for articles, sections, or categories that they can view in Help Center.

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      parameters:
        - name: locales
          in: query
          description: |
            The value given is a comma-separated list of locale names;
            only return translations in those locales
          schema:
            type: string
          example: en-us,en-uk
        - name: outdated
          in: query
          description: Only return translations with the given outdated status
          schema:
            type: boolean
          example: true
        - name: draft
          in: query
          description: Only return translations with the given draft status
          schema:
            type: boolean
          example: true
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/TranslationsResponseExample'
    post:
      operationId: CreateTranslation
      tags:
        - Translations
      summary: Create Translation
      description: |
        Creates a translation for a given [article](/api-reference/help_center/help-center-api/articles), [section](/api-reference/help_center/help-center-api/sections), or [category](/api-reference/help_center/help-center-api/categories). Any locale
        that you specify must be enabled for the current Help Center. The locale must also be
        different from that of any existing translation associated with the source object.

        #### Allowed for

        * Help Center Managers
        * Agents (article translations only)

        The requesting agent can create an article translation only if they can edit the article in Help Center.
      responses:
        "201":
          description: description
          headers:
            Location:
              description: The URL of the new created article attachment
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/translations/{translation_id}.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponse'
              examples:
                default:
                  $ref: '#/components/examples/TranslationResponseExample'
  /api/v2/help_center/articles/{article_id}/translations/{locale}:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
      - $ref: '#/components/parameters/RequiredLocale'
    get:
      operationId: ShowTranslation
      tags:
        - Translations
      summary: Show Translation
      description: |
        #### Allowed for

        * End users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponse'
              examples:
                default:
                  $ref: '#/components/examples/TranslationResponseExample'
    put:
      operationId: UpdateTranslation
      tags:
        - Translations
      summary: Update Translation
      description: |
        When updating a translation, any locale that you specify must be enabled for
        the current Help Center. If you change the translation locale, it must be
        different from that of any existing translation associated with the same
        source object.

        #### Allowed for

        * Agents (only articles)
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationResponse'
              examples:
                default:
                  $ref: '#/components/examples/TranslationResponseExample'
  /api/v2/help_center/articles/{article_id}/translations/missing:
    parameters:
      - $ref: '#/components/parameters/ArticleId'
    get:
      operationId: ListMissingTranslations
      tags:
        - Translations
      summary: List Missing Translations
      description: |
        Lists the locales that don't have a translation for a given [article](/api-reference/help_center/help-center-api/articles), [section](/api-reference/help_center/help-center-api/sections), or [category](/api-reference/help_center/help-center-api/categories).

        #### Allowed for

        * Agents

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalesResponse'
              examples:
                default:
                  $ref: '#/components/examples/MissingTranslationsResponseExample'
  /api/v2/help_center/articles/attachments:
    post:
      operationId: CreateAttachment
      tags:
        - Article Attachments
      summary: Create Unassociated Attachment
      description: |
        You can use this endpoint for bulk imports. It lets you upload a file without associating it
        to an article until later. See [Associate Attachments in Bulk to Article](/api-reference/help_center/help-center-api/articles#associate-attachments-in-bulk-to-article).

         If you plan on adding attachments to article translations, import a separate article attachment for each translation and set the locale in advance. For more information on translation attachments, see [Create Article Attachment](/api-reference/help_center/help-center-api/article_attachments/#create-article-attachment).

        *Notes:*

          - While you can provide a file as a parameter, we recommend you first create a [guide-media](/api-reference/help_center/guide_medias) and then create an article attachment by specifying the `guide_media_id`.
          - Associate attachments to articles as soon as possible. For example, if you use the endpoint to bulk-import inline images, only signed-in end users can see the images; anonymous users don't have permission to view unassociated images. Also, from time to time, we purge old article attachments not associated to any article. To ensure you don't lose an uploaded file, associate it to an article.
        #### Allowed for

          * Agents
      responses:
        "201":
          description: Created Response
          headers:
            Location:
              description: The URL of the new created article attachment
              schema:
                type: string
                format: url
              example: https://{subdomain}.zendesk.com/api/v2/help_center/articles/attachments.json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleAttachmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleAttachmentResponseExample'
  /api/v2/help_center/articles/attachments/{article_attachment_id}:
    parameters:
      - $ref: '#/components/parameters/ArticleAttachmentId'
    delete:
      operationId: DeleteArticleAttachment
      tags:
        - Article Attachments
      summary: Delete Article Attachment
      description: |
        #### Allowed for

        * Agents
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/articles/labels:
    get:
      operationId: ListAllArticleLabels
      tags:
        - Article Labels
      summary: List All Labels
      description: |
        Lists all the labels in the articles in Help Center.

        #### Allowed for

        * Agents

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleLabelsResponseExample'
  /api/v2/help_center/articles/labels/{label_id}:
    parameters:
      - $ref: '#/components/parameters/LabelId'
    get:
      operationId: ShowLabel
      tags:
        - Article Labels
      summary: Show Label
      description: |
        Shows the properties of the specified label.

        #### Allowed for

        * Agents
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleLabelResponseExample'
    delete:
      operationId: DeleteLabel
      tags:
        - Article Labels
      summary: Delete Label
      description: |
        Removes the label from all articles and deletes it.

        #### Allowed for

        * Agents
      responses:
        "204":
          description: Default success response
  /api/v2/help_center/articles/search:
    get:
      operationId: ArticleSearch
      tags:
        - Search
      summary: Search Articles
      description: |
        Returns a default number of 25 articles per page, up to a maximum of 1000 results. See [Pagination](/api-reference/introduction/pagination/). The `per_page` parameter, if provided, must be an integer between 1 and 100.

        The `page` parameter, if provided, must be an integer greater than 0.

        The results are sorted by relevance by default. You can also sort the results by `created_at` or `updated_at`.

        The [article objects](/api-reference/help_center/help-center-api/articles) returned by the search endpoint contain two additional properties:

        | Name        | Type   | Read-only | Mandatory | Comment
        |-------------|--------|-----------|-----------|-------
        | result_type | string | yes       | no        | For articles, always the string "article"
        | snippet     | string | yes       | no        | The portion of an article that is relevant to the search query, with matching words or phrases delimited by `<em></em>` tags. Example: a query for "carrot potato" might return the snippet "...don't confuse `<em>`carrots`</em>` with `<em>`potatoes`</em>`..."

        You must specify at least one of the following parameters in your request:

        - query
        - category
        - section
        - label_names

        #### Pagination

        - Offset pagination only

        See [Pagination](/api-reference/introduction/pagination/).

        Returns a maximum of 100 articles per page.

        #### Allowed for

        * Anonymous users
      parameters:
        - name: query
          in: query
          description: |
            The search text to be matched or a search string. Examples: "carrot potato", "'carrot potato'".
          schema:
            type: string
        - name: category
          in: query
          description: Limit the search to this category id. See [Filtering by Category](#filtering-by-category)
          schema:
            type: integer
        - name: section
          in: query
          description: Limit the search to this section id. See [Filtering by Section](#filtering-by-section)
          schema:
            type: integer
        - name: label_names
          in: query
          description: A comma-separated list of label names. See [Filtering by Labels](#filtering-by-labels)
          schema:
            type: string
        - name: locale
          in: query
          description: Search for articles in the specified locale. See [Filtering by Locale](#filtering-by-locale)
          schema:
            type: string
        - name: multibrand
          in: query
          description: |
            Enable search across all brands if true. Defaults to false if omitted.
          schema:
            type: boolean
        - name: brand_id
          in: query
          description: |
            Search for articles in the specified brand.
          schema:
            type: integer
        - name: created_before
          in: query
          description: |
            Limit the search to articles created before a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: created_after
          in: query
          description: |
            Limit the search to articles created after a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: created_at
          in: query
          description: |
            Limit the search to articles created on a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: updated_before
          in: query
          description: |
            Limit the search to articles updated before a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: updated_after
          in: query
          description: |
            Limit the search to articles updated after a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: updated_at
          in: query
          description: |
            Limit the search to articles updated on a given date (format YYYY-MM-DD).
          schema:
            type: string
            format: date-time
        - name: sort_by
          in: query
          description: One of created_at or updated_at. Defaults to sorting by relevance
          schema:
            type: string
        - name: sort_order
          in: query
          description: One of asc or desc. Defaults to desc
          schema:
            type: string
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleSearchResponse'
              examples:
                default:
                  $ref: '#/components/examples/ArticleSearchResponseExample'
  /api/v2/help_center/community_posts/search:
    get:
      operationId: CommunityPostSearch
      tags:
        - Search
      summary: Search Posts
      description: |
        Returns a maximum of 25 posts per page, up to a maximum of 1000 results. See [Pagination](/api-reference/introduction/pagination/).

        The results are sorted by relevance by default. You can also sort the results by `created_at` or `updated_at`.

        #### Pagination

        - Offset pagination only

        See [Pagination](/api-reference/introduction/pagination/).

        Returns a maximum of 100 articles per page.

        #### Allowed for

        * End users
      parameters:
        - name: query
          in: query
          description: |
            Search text to be matched or a search string. Examples: "carrot potato", "''carrot potato''"'
          required: true
          schema:
            type: string
          example: help center
        - name: topic
          in: query
          description: Search by topic ID. See [Filtering by Topic](#filtering-by-topic)
          schema:
            type: integer
        - name: created_before
          in: query
          description: the search to posts created before a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: created_after
          in: query
          description: Search  posts created after a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: created_at
          in: query
          description: Search posts created on a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: updated_before
          in: query
          description: Search posts updated before a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: updated_after
          in: query
          description: Search posts updated after a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: updated_at
          in: query
          description: Search posts updated on a given date (format YYYY-MM-DD)
          schema:
            type: string
            format: date-time
        - name: sort_by
          in: query
          description: Sort by `created_at` or `updated_at`. Defaults to sorting by relevance
          schema:
            type: string
        - name: sort_order
          in: query
          description: Sort in ascending or descending order. Default is descending order.
          schema:
            type: string
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityPostSearchResponse'
              examples:
                default:
                  $ref: '#/components/examples/CommunityPostSearchResponseExample'
  /api/v2/help_center/locales:
    get:
      operationId: ListLocales
      tags:
        - Translations
      summary: List Enabled Locales and Default Locale
      description: |
        #### Allowed for

         * End users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalesWithDefaultResponse'
              examples:
                default:
                  $ref: '#/components/examples/LocalesWithDefaultResponseExample'
  /api/v2/help_center/sessions:
    get:
      operationId: ShowSession
      tags:
        - Sessions
      summary: Show Session
      description: |
        #### Allowed for

         * Anonymous users
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
              examples:
                default:
                  $ref: '#/components/examples/SessionResponseExample'
  /api/v2/help_center/translations/{translation_id}:
    parameters:
      - $ref: '#/components/parameters/TranslationId'
    delete:
      operationId: DeleteTranslation
      tags:
        - Translations
      summary: Delete Translation
      description: |
        Deletes a translation, provided it's not the only translation for the source object.

        #### Allowed for

        * Agents
      responses:
        "204":
          description: Delete response
  /api/v2/help_center/user_segments:
    get:
      operationId: ListUserSegments
      tags:
        - User Segments
      summary: List User Segments
      description: |
        Some user segments can only be applied to sections and topics on certain Guide plans. For instance, user segments with a `user_type` of `"staff"` cannot be applied to sections and topics on accounts on the Guide Lite plan or the Suite Team plan. To request only user segments applicable on the account's current Suite plan, use the `/api/v2/help_center/user_segments/applicable.json` endpoint.

        The `/api/v2/help_center/users/{user_id}/user_segments.json` endpoint returns the list of user segments that a particular user belongs to. This is the only list endpoint that agents have access to. When an agent makes a request to this endpoint with another user's id, the response only includes user segments that the requesting agent also belongs to.

        These endpoints support pagination, as described in the [pagination documentation](/api-reference/introduction/pagination/).

        #### Allowed for

        * Help Center managers
        * Agents

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      parameters:
        - name: built_in
          in: query
          description: Only built_in user segments if true, only custom user segments if false
          allowEmptyValue: true
          schema:
            type: boolean
      responses:
        "200":
          description: OK response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSegmentsResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentsResponseExample'
    post:
      operationId: CreateUserSegment
      tags:
        - User Segments
      summary: Create User Segment
      description: |
        #### Allowed for

        * Help Center managers
      responses:
        "201":
          description: Created response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSegmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentResponseExample'
        "400":
          description: Bad request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                default:
                  $ref: '#/components/examples/BadRequestCreateUserSegment'
  /api/v2/help_center/user_segments/{user_segment_id}:
    parameters:
      - $ref: '#/components/parameters/UserSegmentId'
    get:
      operationId: ShowUserSegment
      tags:
        - User Segments
      summary: Show User Segment
      description: |
        #### Allowed for

        * Help Center managers

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSegmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentResponseExample'
    put:
      operationId: UpdateUserSegment
      tags:
        - User Segments
      summary: Update User Segment
      description: |
        #### Allowed for

        * Help Center managers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSegmentResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentResponseExample'
        "400":
          description: Bad request Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
              examples:
                default:
                  $ref: '#/components/examples/BadRequestUpdateUserSegment'
    delete:
      operationId: DeleteUserSegment
      tags:
        - User Segments
      summary: Delete User Segment
      description: |
        #### Allowed for

        * Help Center managers
      responses:
        "204":
          description: Response when the object was deleted
  /api/v2/help_center/user_segments/{user_segment_id}/sections:
    parameters:
      - $ref: '#/components/parameters/UserSegmentId'
    get:
      operationId: ListUserSegmentSections
      tags:
        - User Segments
      summary: List Sections with User Segment
      description: |
        Lists the sections that use the specified user segment.

        This endpoint supports pagination as described in [Pagination](/api-reference/help_center/help-center-api/help-center-api/#pagination).

        #### Allowed for

        * Help Center managers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SectionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentSectionsResponseExample'
  /api/v2/help_center/user_segments/{user_segment_id}/topics:
    parameters:
      - $ref: '#/components/parameters/UserSegmentId'
    get:
      operationId: ListUserSegmentTopics
      tags:
        - User Segments
      summary: List Topics with User Segment
      description: |
        Lists the topics that use the specified user segment.

        This endpoint supports pagination as described in [Pagination](/api-reference/help_center/help-center-api/help-center-api/#pagination).

        #### Allowed for

        * Help Center managers

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicsResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSegmentTopicsResponseExample'
  /api/v2/help_center/users/{user_id}/subscriptions:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: ListContentSubscriptionsByUserId
      tags:
        - Content Subscriptions
      summary: List Content Subscriptions By User
      description: |
        Lists the content subscriptions of a given user. To list your own subscriptions,
        specify `me` as the user id.

        #### Allowed for

        * End users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
        | articles      | articles      | article subscriptions
        | sections      | sections      | section subscriptions
        | questions     | questions     | question subscriptions
        | topics        | topics        | topic subscriptions
        | translations  | translations  | article or section subscriptions
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ContentSubscriptionsResponseExample'
  /api/v2/help_center/users/{user_id}/user_subscriptions:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: ListUserSubscriptionsByUserId
      tags:
        - User Subscriptions
      summary: List User Subscriptions By User
      description: |
        Lists the user subscriptions of a given user. To list your own subscriptions,
        specify `me` as the user id.

        #### Allowed for

        * End users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).

        #### Sideloads

        The following sideloads are supported:

        | Name          | Will sideload | For
        |---------------|---------------|----
        | users         | users         | all
      parameters:
        - name: type
          in: query
          description: |
            Selects whether to find who the given user is following ("followings")
            or who is following the given user ("followers").
            The default is "followers".
          schema:
            type: string
            enum:
              - followings
              - followers
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSubscriptionsResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserSubscriptionsResponseExample'
  /api/v2/help_center/users/{user_id}/votes:
    parameters:
      - $ref: '#/components/parameters/UserId'
    get:
      operationId: ListUserVotes
      tags:
        - Votes
      summary: List Votes
      description: |
        Lists all votes cast by a given user, or all votes cast by all users for a given article, article comment, post, or post comment.

        To list only your own votes, specify `me` as the user id.

        The `{locale}` for article and article comment votes is required only for end users. Admins and agents can omit it.

        #### Allowed for

        * End users

        #### Pagination

        * Cursor pagination (recommended)
        * Offset pagination

        See [Pagination](/api-reference/introduction/pagination/).
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VotesResponse'
              examples:
                default:
                  $ref: '#/components/examples/UserVotesResponseExample'
  /api/v2/help_center/votes/{vote_id}:
    parameters:
      - $ref: '#/components/parameters/VoteId'
    get:
      operationId: ShowVote
      tags:
        - Votes
      summary: Show Vote
      description: |
        #### Allowed for

        * End users

        #### Sideloads
        The following sideloads are supported:

        | Name          | Will sideload
        |---------------|--------------
        | users         | authors
        | articles      | articles
        | translations  | translations of any sideloaded articles
        | posts         | posts
        | comments      | comments

        Note that you must sideload `articles` in order to sideload `translations`.
      responses:
        "200":
          description: OK Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoteResponse'
              examples:
                default:
                  $ref: '#/components/examples/VoteResponseExample'
    delete:
      operationId: DeleteVote
      tags:
        - Votes
      summary: Delete Vote
      description: |
        #### Allowed for

        * End users
      responses:
        "204":
          description: Default success response
components:
  schemas:
    ArticleAttachmentObject:
      type: object
      properties:
        article_id:
          type: integer
          description: The associated article, if present
        content_type:
          type: string
          description: 'The file type. Example: image/png'
          readOnly: true
        content_url:
          type: string
          description: URL where the attachment file can be downloaded
          readOnly: true
        created_at:
          type: string
          description: The time the article attachment was created
          readOnly: true
        file:
          type: object
          description: File to upload, applicable only during creation.
        file_name:
          type: string
          description: The file name
          readOnly: true
        guide_media_id:
          type: string
          description: Unique identifier for the guide-media to associate with this attachment, applicable only during creation.
        id:
          type: integer
          description: Assigned ID when the article attachment is created
          readOnly: true
        inline:
          type: boolean
          description: The attached file is shown in the admin interface for inline attachments. Its URL can be referenced in the article's HTML body. Inline attachments are image files directly embedded in the article body. If false, the attachment is listed in the list of attachments. The default value is false
        locale:
          type: string
          description: The locale of translation that the attachment will be attached to and can only be set on inline attachments
        size:
          type: integer
          description: The attachment file size in bytes
          readOnly: true
        updated_at:
          type: string
          description: The time the article attachment was last updated
          readOnly: true
        url:
          type: string
          description: The URL of the article attachment
          readOnly: true
      example:
        article_id: 23
        content_type: application/pdf
        content_url: https://company.zendesk.com/hc/article_attachments/200109629
        created_at: "2012-04-04T09:14:57Z"
        file_name: party_invitation.pdf
        id: 1428
        inline: false
        locale: en_us
        size: 58298
    ArticleAttachmentResponse:
      type: object
      properties:
        article_attachment:
          $ref: '#/components/schemas/ArticleAttachmentObject'
    ArticleAttachmentsResponse:
      type: object
      properties:
        article_attachments:
          type: array
          items:
            $ref: '#/components/schemas/ArticleAttachmentObject'
    ArticleObject:
      type: object
      properties:
        author_id:
          type: integer
          description: The id of the user who wrote the article (set to the user who made the request on create by default)
        body:
          type: string
          description: HTML body of the article. Unsafe tags and attributes may be removed before display. For a list of safe tags and attributes, see [Allowing unsafe HTML in Help Center articles](https://support.zendesk.com/hc/en-us/articles/115015895948) in Zendesk help
        comments_disabled:
          type: boolean
          description: True if comments are disabled; false otherwise
        content_tag_ids:
          type: array
          description: The list of content tags attached to the article
          items:
            type: string
        created_at:
          type: string
          description: The time the article was created
          readOnly: true
        draft:
          type: boolean
          description: True if the translation for the current locale is a draft; false otherwise. false by default. Can be set when creating but not when updating. For updating, see Translations
          readOnly: true
        edited_at:
          type: string
          description: The time the article was last edited in its displayed locale
          readOnly: true
        html_url:
          type: string
          description: The url of the article in Help Center
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the article is created
          readOnly: true
        label_names:
          type: array
          description: An array of label names associated with this article. By default no label names are used. Only available on certain plans
          items:
            type: string
        locale:
          type: string
          description: The locale that the article is being displayed in
        outdated:
          type: boolean
          description: Deprecated. Always false because the source translation is always the most up-to-date translation
          readOnly: true
        outdated_locales:
          type: array
          description: Locales in which the article was marked as outdated
          items:
            type: string
          readOnly: true
        permission_group_id:
          type: integer
          description: The id of the permission group which defines who can edit and publish this article
        position:
          type: integer
          description: The position of this article in the article list. 0 by default
        promoted:
          type: boolean
          description: True if this article is promoted; false otherwise. false by default
        section_id:
          type: integer
          description: The id of the section to which this article belongs
        source_locale:
          type: string
          description: The source (default) locale of the article
          readOnly: true
        title:
          type: string
          description: The title of the article
        updated_at:
          type: string
          description: The time the article was last updated
          readOnly: true
        url:
          type: string
          description: The API url of the article
          readOnly: true
        user_segment_id:
          type: integer
          description: The id of the user segment which defines who can see this article. Set to null to make it accessible to everyone. Either user_segment_id or user_segment_ids must be specified
          nullable: true
        user_segment_ids:
          type: array
          description: List of user segment ids which define who can view this article. Set to an empty list to make it accessible to everyone. For Enterprise plans only this may contain more than one user_segment_id. Either user_segment_id or user_segment_ids must be specified
        vote_count:
          type: integer
          description: The total number of upvotes and downvotes
          readOnly: true
        vote_sum:
          type: integer
          description: The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
          readOnly: true
      example:
        author_id: 3465
        comments_disabled: false
        id: 1635
        locale: en
        permission_group_id: 13
        title: The article
        user_segment_id: 12
      required:
        - title
        - locale
        - permission_group_id
    ArticleRequest:
      type: object
      properties:
        article:
          type: object
          properties:
            body:
              type: string
              example: Use a tripod
            locale:
              type: string
              example: en-us
            permission_group_id:
              type: integer
              default: 0
              example: 56
            title:
              type: string
              example: Taking photos in low light
            user_segment_id:
              type: integer
              example: 123
          required:
            - title
            - locale
            - user_segment_id
            - permission_group_id
        notify_subscribers:
          type: boolean
          example: false
      required:
        - article
    ArticleResponse:
      type: object
      properties:
        article:
          $ref: '#/components/schemas/ArticleObject'
    ArticleSearchResponse:
      type: object
      properties:
        result_type:
          type: string
          description: For articles, always the string `article`
          default: article
          readOnly: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/ArticleObject'
        snippet:
          type: string
          description: |
            The portion of an article that is relevant to the search query, with matching words or phrases delimited by <em></em> tags. Example: a query for `carrot potato` might return the snippet `...don't confuse <em>carrots</em> with <em>potatoes</em>...`
          readOnly: true
    ArticlesResponse:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/ArticleObject'
    BadRequestErrorResponse:
      type: object
      properties:
        errors:
          type: object
          additionalProperties: true
      example:
        errors:
          field_name_with_error:
            - cannot process this field
    CategoriesResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObject'
    CategoryObject:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: The time at which the category was created
          readOnly: true
        description:
          type: string
          description: The description of the category
        html_url:
          type: string
          description: The url of this category in Help Center
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when creating categories
          readOnly: true
        locale:
          type: string
          description: The locale where the category is displayed
        name:
          type: string
          description: The name of the category
        outdated:
          type: boolean
          description: Whether the category is out of date
          readOnly: true
        position:
          type: integer
          description: The position of this category relative to other categories
        source_locale:
          type: string
          description: The source (default) locale of the category
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: The time at which the category was last updated
          readOnly: true
        url:
          type: string
          description: The API url of this category
          readOnly: true
      example:
        description: ""
        html_url: https://company.zendesk.com/hc/en-us/categories/354362577
        id: 1635
        locale: en-us
        name: Self Help Articles
        source_locale: en-us
        url: https://company.zendesk.com/api/v2/help_center/categories/354362577
      required:
        - id
        - name
        - locale
    CategoryResponse:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/CategoryObject'
    CommentObject:
      type: object
      properties:
        author_id:
          type: integer
          description: The id of the author of this comment. Writable on create by Help Center managers. See [Create Comment](#create-comment)
        body:
          type: string
          description: The comment made by the author. See [User content](#user-content)
        created_at:
          type: string
          description: The time the comment was created. Writable on create by Help Center managers. See [Create Comment](#create-comment)
        html_url:
          type: string
          description: The url at which the comment is presented in Help Center
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the comment is created
          readOnly: true
        locale:
          type: string
          description: The locale in which this comment was made
        non_author_editor_id:
          type: integer
          description: The user id of whoever performed the most recent (if any) non-author edit. A non-author edit consists of an edit make by a user other than the author that creates or updates the `body` or `author_id`. Note that only edits made after May 17, 2021 will be reflected in this field. If no non-author edits have occured since May 17, 2021, then this field will be `null`.
          readOnly: true
        non_author_updated_at:
          type: string
          format: date-time
          description: When the comment was last edited by a non-author user
          readOnly: true
        source_id:
          type: integer
          description: The id of the item on which this comment was made
          readOnly: true
        source_type:
          type: string
          description: The type of the item on which this comment was made. Currently only supports 'Article'
          readOnly: true
        updated_at:
          type: string
          description: The time at which the comment was last updated
          readOnly: true
        url:
          type: string
          description: The API url of this comment
          readOnly: true
        vote_count:
          type: integer
          description: The total number of upvotes and downvotes
          readOnly: true
        vote_sum:
          type: integer
          description: The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
          readOnly: true
      example:
        author_id: 3465
        body: Thanks for your help!
        created_at: "2012-04-04T09:14:57Z"
        id: 1635
        locale: en-us
        source_id: 65466
        source_type: Article
      required:
        - body
        - locale
    CommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/CommentObject'
    CommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/CommentObject'
    CommunityPostSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PostObject'
    ContentSubscriptionObject:
      type: object
      properties:
        content_id:
          type: integer
          description: The id of the subscribed item
          readOnly: true
        content_type:
          type: string
          description: The type of the subscribed item
          readOnly: true
        created_at:
          type: string
          description: The time at which the subscription was created
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the subscription is created
          readOnly: true
        include_comments:
          type: boolean
          description: Subscribe also to article comments / post comments. Only for section / topic subscriptions.
          readOnly: true
        locale:
          type: string
          description: The locale of the subscribed item
          readOnly: true
        source_locale:
          type: string
          description: Used only for [Create Section Subscription](#create-section-subscription) and [Create Article Subscription](#create-article-subscription), where it's mandatory. Selects the locale of the content to be subscribed
        updated_at:
          type: string
          description: The time at which the subscription was last updated
          readOnly: true
        url:
          type: string
          description: The API url of the subscription
          readOnly: true
        user_id:
          type: integer
          description: The id of the user who has this subscription
          readOnly: true
      example:
        content_id: 65466
        created_at: "2012-04-04T09:14:57Z"
        id: 1635
        locale: en-us
        user_id: 3465
      required:
        - locale
    ContentSubscriptionsResponse:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/ContentSubscriptionObject'
    CreateUserImageResponse:
      type: object
      properties:
        user_image:
          type: object
          properties:
            content_type:
              type: string
            path:
              type: string
            size:
              type: number
    LabelObject:
      type: object
      properties:
        created_at:
          type: string
          description: The time at which the label was created
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the label is created
          readOnly: true
        name:
          type: string
          description: The actual name of the label
        updated_at:
          type: string
          description: The time at which the label was last updated
          readOnly: true
        url:
          type: string
          description: The API url of this label
          readOnly: true
      example:
        created_at: "2012-04-04T09:14:57Z"
        id: 2003
        name: instructions
      required:
        - name
    LabelResponse:
      type: object
      properties:
        label:
          $ref: '#/components/schemas/LabelObject'
    LabelsResponse:
      type: object
      properties:
        labels:
          type: array
          items:
            $ref: '#/components/schemas/LabelObject'
    LocalesResponse:
      type: object
      properties:
        locales:
          type: array
          items:
            type: string
    LocalesWithDefaultResponse:
      type: object
      properties:
        default_locale:
          type: string
        locales:
          type: array
          items:
            type: string
    PostCommentObject:
      type: object
      properties:
        author_id:
          type: integer
          description: The id of the author of the comment. Writable on create by Help Center managers. See [Create Post Comment](#create-post-comment)
        body:
          type: string
          description: The comment made by the author. See [User content](#user-content)
        created_at:
          type: string
          description: When the comment was created. Writable on create by Help Center managers. See [Create Post Comment](#create-post-comment)
        html_url:
          type: string
          description: The community url of the comment
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the comment is created
          readOnly: true
        non_author_editor_id:
          type: integer
          description: The user id of whoever performed the most recent (if any) non-author edit. A non-author edit consists of an edit make by a user other than the author that creates or updates the `body`. Note that only edits made after May 17, 2021 will be reflected in this field. If no non-author edits have occured since May 17, 2021, then this field will be `null`.
          readOnly: true
        non_author_updated_at:
          type: string
          format: date-time
          description: When the comment was last edited by a non-author user
          readOnly: true
        official:
          type: boolean
          description: Whether the comment is marked as official
        post_id:
          type: integer
          description: The id of the post on which the comment was made
          readOnly: true
        updated_at:
          type: string
          description: When the comment was last updated
          readOnly: true
        url:
          type: string
          description: The API url of the comment
          readOnly: true
        vote_count:
          type: integer
          description: The total number of upvotes and downvotes
          readOnly: true
        vote_sum:
          type: integer
          description: The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
          readOnly: true
      example:
        author_id: 89567
        body: My printer is on fire!
        id: 35467
        official: false
        vote_count: 15
        vote_sum: 10
      required:
        - body
    PostCommentResponse:
      type: object
      properties:
        comment:
          $ref: '#/components/schemas/PostCommentObject'
    PostCommentsResponse:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: '#/components/schemas/PostCommentObject'
    PostObject:
      type: object
      properties:
        author_id:
          type: integer
          description: The id of the author of the post. *Writable on create by Help Center managers -- see Create Post
          readOnly: true
        closed:
          type: boolean
          description: Whether further comments are allowed
        comment_count:
          type: integer
          description: The number of comments on the post
          readOnly: true
        content_tag_ids:
          type: array
          description: The list of content tags attached to the post
          items:
            type: integer
        created_at:
          type: string
          format: date-time
          description: When the post was created. Writable on create by Help Center managers -- see [Create Post](#create-post)
          readOnly: true
        details:
          type: string
          description: The details of the post made by the author. See [User content](#user-content)
        featured:
          type: boolean
          description: Whether the post is featured
        follower_count:
          type: integer
          description: The number of followers of the post
          readOnly: true
        html_url:
          type: string
          description: The community url of the post
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the post is created
          readOnly: true
        non_author_editor_id:
          type: integer
          description: The user id of whoever performed the most recent (if any) non-author edit. A non-author edit consists of an edit make by a user other than the author that creates or updates the `title` or `details`. Note that only edits made after May 17, 2021 will be reflected in this field. If no non-author edits have occured since May 17, 2021, then this field will be `null`.
          readOnly: true
        non_author_updated_at:
          type: string
          format: date-time
          description: When the post was last edited by a non-author user
          readOnly: true
        pinned:
          type: boolean
          description: When true, pins the post to the top of its topic
        status:
          type: string
          description: 'The status of the post. Possible values: "planned", "not_planned" , "answered", or "completed"'
        title:
          type: string
          description: The title of the post
        topic_id:
          type: integer
          description: The id of the topic that the post belongs to
        updated_at:
          type: string
          format: date-time
          description: When the post was last updated
          readOnly: true
        url:
          type: string
          description: The API url of the post
          readOnly: true
        vote_count:
          type: integer
          description: The total number of upvotes and downvotes
          readOnly: true
        vote_sum:
          type: integer
          description: The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
          readOnly: true
      example:
        author_id: 3465
        featured: true
        id: 1635
        title: The post
      required:
        - title
    PostResponse:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/PostObject'
    PostsResponse:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/PostObject'
    RequestUserImageUploadResponse:
      type: object
      properties:
        upload:
          type: object
          properties:
            headers:
              type: object
              additionalProperties: true
            token:
              type: string
            url:
              type: string
    SearchObject:
      type: object
      properties:
        results:
          type: array
          description: An array with the base articles or community posts
          items:
            oneOf:
              - $ref: '#/components/schemas/ArticleObject'
              - $ref: '#/components/schemas/PostCommentObject'
      required:
        - results
    SectionObject:
      type: object
      properties:
        category_id:
          type: integer
          description: The id of the category to which this section belongs
        created_at:
          type: string
          description: The time at which the section was created
          readOnly: true
        description:
          type: string
          description: The description of the section
        html_url:
          type: string
          description: The url of this section in HC
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when creating subscriptions
          readOnly: true
        locale:
          type: string
          description: The locale in which the section is displayed
        name:
          type: string
          description: The name of the section
        outdated:
          type: boolean
          description: Whether the section is out of date
          readOnly: true
        parent_section_id:
          type: integer
          description: The id of the section to which this section belongs. Only writable for Guide Enterprise customers
          nullable: true
        position:
          type: integer
          description: The position of this section in the section list. Used when sorting is set to ´manual´. By default the section is added to the end of the list
        source_locale:
          type: string
          description: The source (default) locale of the section
          readOnly: true
        theme_template:
          type: string
          description: The theme template name used to display this section in Help Center.
          example: section_template
        updated_at:
          type: string
          description: The time at which the section was last updated
          readOnly: true
        url:
          type: string
          description: The API url of this section
          readOnly: true
      example:
        category_id: 3465
        description: This section contains tricks for the airborne
        id: 1635
        locale: en-us
        name: Avionics
      required:
        - name
        - locale
    SectionPutRequest:
      type: object
      properties:
        section:
          type: object
          properties:
            category_id:
              type: integer
              description: The id of the category to which this section belongs
            description:
              type: string
              description: The description of the section
            name:
              type: string
              description: The name of the section
            parent_section_id:
              type: integer
              description: The id of the section to which this section belongs. Only writable for Guide Enterprise customers
            position:
              type: integer
              description: The position of this section in the section list. Used when sorting is set to ´manual´.
            sorting:
              type: string
              description: Defines the type of sorting used in this section
              enum:
                - manual
                - title
                - creation_desc
                - creation_asc
            theme_template:
              type: string
              description: The theme template name used to display this section in Help Center.
              example: section_template
      required:
        - section
    SectionResponse:
      type: object
      properties:
        section:
          $ref: '#/components/schemas/SectionObject'
    SectionsResponse:
      type: object
      properties:
        sections:
          type: array
          items:
            $ref: '#/components/schemas/SectionObject'
    SessionObject:
      type: object
      properties:
        csrf_token:
          type: string
    SessionResponse:
      type: object
      properties:
        current_session:
          $ref: '#/components/schemas/SessionObject'
    SubscriptionResponse:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/ContentSubscriptionObject'
    TopicObject:
      type: object
      description: |
        The `manageable_by` attribute takes one of the following values:

        | Value     | Users                       |
        |-----------|---------------------------- |
        | staff     | agents and managers         |
        | managers  | only Help Center managers   |

        Note that `manageable_by` is only displayed to users who can manage the topic.
      properties:
        created_at:
          type: string
          description: When the topic was created
          readOnly: true
        description:
          type: string
          description: The description of the topic. By default an empty string
          nullable: true
        follower_count:
          type: integer
          description: The number of users following the topic
          readOnly: true
        html_url:
          type: string
          description: The community url of the topic
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the topic is created
          readOnly: true
        manageable_by:
          type: string
          description: The set of users who can manage this topic.
          enum:
            - staff
            - managers
        name:
          type: string
          description: The name of the topic
        position:
          type: integer
          description: The position of the topic relative to other topics in the community
        updated_at:
          type: string
          description: When the topic was last updated
          readOnly: true
        url:
          type: string
          description: The API url of the topic
          readOnly: true
        user_segment_id:
          type: integer
          description: The id of the user segment to which this topic belongs
          nullable: true
      example:
        created_at: "2012-04-04T09:14:57Z"
        description: Security Best Practices
        follower_count: 332
        id: 1635
        manageable_by: staff
        name: Security
      required:
        - name
    TopicResponse:
      type: object
      properties:
        topic:
          $ref: '#/components/schemas/TopicObject'
    TopicsResponse:
      type: object
      properties:
        topics:
          type: array
          items:
            $ref: '#/components/schemas/TopicObject'
    TranslationObject:
      type: object
      properties:
        body:
          type: string
          description: HTML body of the translation. Empty by default
        created_at:
          type: string
          description: The time at which the translation was created
          readOnly: true
        created_by_id:
          type: integer
          description: The id of the user who created the translation
          readOnly: true
        draft:
          type: boolean
          description: True if the translation is a draft; false otherwise. False by default
        html_url:
          type: string
          description: The url of the translation in Help Center
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when a translation is created
          readOnly: true
        locale:
          type: string
          description: The locale of the translation
        outdated:
          type: boolean
          description: True if the translation is outdated; false otherwise. False by default
        source_id:
          type: integer
          description: The id of the item that has this translation
          readOnly: true
        source_type:
          type: string
          description: The type of the item that has this translation. Can be "article", "section", or "category".
          readOnly: true
        title:
          type: string
          description: The title of the translation
        updated_at:
          type: string
          description: The time at which the translation was last updated
          readOnly: true
        updated_by_id:
          type: integer
          description: The id of the user who last updated the translation
          nullable: true
          readOnly: true
        url:
          type: string
          description: The API url of the translation
          readOnly: true
      example:
        id: 3243452
        locale: en
        source_id: 768934
        source_type: Article
        title: Hello translation
      required:
        - locale
        - title
    TranslationResponse:
      type: object
      properties:
        translation:
          $ref: '#/components/schemas/TranslationObject'
    TranslationsResponse:
      type: object
      properties:
        translations:
          type: array
          items:
            $ref: '#/components/schemas/TranslationObject'
    UnifiedSearchResult:
      type: object
      properties:
        title:
          type: string
        type:
          type: string
          enum:
            - ARTICLE
            - POST
            - EXTERNAL_RECORD
        updated_at:
          type: string
          format: date-time
        url:
          type: string
    UnifiedSearchResultSet:
      type: object
      properties:
        meta:
          type: object
          properties:
            after_cursor:
              type: string
            before_cursor:
              type: string
            has_more:
              type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedSearchResult'
    UserSegmentObject:
      type: object
      description: |
        The `user_type` attribute takes one of the following values:

        | Value               | Users                                |
        |---------------------|--------------------------------------|
        | signed_in_users     | only authenticated users             |
        | staff               | only agents and Help Center managers |


        For `group_ids`, `organization_ids`, `tags`, and `or_tags`,
        an empty array means that access is not restricted by the attribute. For example,
        if no group ids are specified, then users don't have to be in any specific group to
        have access.

        For `tags`, a user must have all the listed tags to have access. For `or_tags`, a
        user must have at least one of the listed tags to have access.
      properties:
        added_user_ids:
          type: array
          description: The ids of users added specifically to this user segment, regardless of matching tags or other criteria
          items:
            type: integer
        built_in:
          type: boolean
          description: Whether the user segment is built-in. Built-in user segments cannot be modified
          readOnly: true
        created_at:
          type: string
          description: When the user segment was created
          readOnly: true
        group_ids:
          type: array
          description: The ids of the groups that have access
          items:
            type: integer
        id:
          type: integer
          description: Automatically assigned when the user segment is created
          readOnly: true
        name:
          type: string
          description: User segment name (localized to the locale of the current user for built-in user segments)
        or_tags:
          type: array
          description: A user must have at least one tag in the list to have access
          items:
            type: string
        organization_ids:
          type: array
          description: The ids of the organizations that have access
          items:
            type: integer
        tags:
          type: array
          description: All the tags a user must have to have access
          items:
            type: string
        updated_at:
          type: string
          description: When the user segment was last updated
          readOnly: true
        user_type:
          type: string
          description: The set of users who can view content
      example:
        built_in: false
        created_at: "2017-07-20T22:55:29Z"
        group_ids:
          - 12
        name: VIP agents
        organization_ids:
          - 42
        tags:
          - vip
        updated_at: "2017-07-23T21:43:28Z"
        user_type: staff
      required:
        - user_type
    UserSegmentResponse:
      type: object
      properties:
        user_segment:
          $ref: '#/components/schemas/UserSegmentObject'
    UserSegmentsResponse:
      type: object
      properties:
        user_segments:
          type: array
          items:
            $ref: '#/components/schemas/UserSegmentObject'
    UserSubscriptionObject:
      type: object
      properties:
        followed_id:
          type: integer
          description: The id of the user being followed
          readOnly: true
        follower_id:
          type: integer
          description: The id of the user doing the following
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the subscription is created
          readOnly: true
      example:
        followed_id: 65466
        follower_id: 98354
        id: 1635
      required:
        - followed_id
        - follower_id
        - id
    UserSubscriptionsResponse:
      type: object
      properties:
        user_subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/UserSubscriptionObject'
    VoteObject:
      type: object
      properties:
        created_at:
          type: string
          description: The time at which the vote was created
          readOnly: true
        id:
          type: integer
          description: Automatically assigned when the vote is created
          readOnly: true
        item_id:
          type: integer
          description: The id of the item for which this vote was cast
          readOnly: true
        item_type:
          type: string
          description: The type of the item. Can be "Article", "Comment", "Post" or "PostComment"
          readOnly: true
        updated_at:
          type: string
          description: The time at which the vote was last updated
          readOnly: true
        url:
          type: string
          description: The API url of this vote
          readOnly: true
        user_id:
          type: integer
          description: The id of the user who cast this vote
          readOnly: true
        value:
          type: integer
          description: The value of the vote
      example:
        created_at: "2012-04-04T09:14:57Z"
        id: 1635
        item_id: 65466
        item_type: Article
        user_id: 3465
        value: 1
      required:
        - value
    VoteResponse:
      type: object
      properties:
        vote:
          $ref: '#/components/schemas/VoteObject'
    VotesResponse:
      type: object
      properties:
        votes:
          type: array
          items:
            $ref: '#/components/schemas/VoteObject'
  parameters:
    ArticleAttachmentId:
      name: article_attachment_id
      in: path
      description: The unique ID of the article attachment
      required: true
      schema:
        type: integer
      example: 1428
    ArticleId:
      name: article_id
      in: path
      description: The unique ID of the article
      required: true
      schema:
        type: integer
      example: 360026053753
    ArticlesSortBy:
      name: sort_by
      in: query
      description: Sorts the articles by one of the accepted values
      schema:
        type: string
        enum:
          - position
          - title
          - created_at
          - updated_at
    CategoryId:
      name: category_id
      in: path
      description: The unique ID of the category
      required: true
      schema:
        type: integer
      example: 360002011513
    CommentId:
      name: comment_id
      in: path
      description: The unique ID of the comment
      required: true
      schema:
        type: integer
      example: 360004163994
    LabelId:
      name: label_id
      in: path
      description: The unique ID of the label
      required: true
      schema:
        type: integer
      example: 360015727233
    OptionalLocale:
      name: locale
      in: path
      description: The locale the item is displayed in
      required: true
      schema:
        type: string
        example: en-us
      example: en-us
    PostCommentId:
      name: post_comment_id
      in: path
      description: The unique ID of the post comment
      required: true
      schema:
        type: integer
      example: 360010837133
    PostId:
      name: post_id
      in: path
      description: The unique ID of the post
      required: true
      schema:
        type: integer
      example: 360039436873
    RequiredLocale:
      name: locale
      in: path
      description: Mandatory locale parameter
      required: true
      schema:
        type: string
        example: en-us
      example: en-us
    SectionId:
      name: section_id
      in: path
      description: The unique ID of the section
      required: true
      schema:
        type: integer
      example: 360004785313
    SortBy:
      name: sort_by
      in: query
      description: Sorts the results by one of the accepted values
      schema:
        type: string
        enum:
          - position
          - created_at
          - updated_at
    SortOrder:
      name: sort_order
      in: query
      description: Selects the order of the results
      schema:
        type: string
        enum:
          - asc
          - desc
    SubscriptionId:
      name: subscription_id
      in: path
      description: The unique ID of the subscription
      required: true
      schema:
        type: integer
      example: 1234
    TopicId:
      name: topic_id
      in: path
      description: The unique ID of the topic
      required: true
      schema:
        type: integer
      example: 360001326113
    TranslationId:
      name: translation_id
      in: path
      description: The unique ID of the translation
      required: true
      schema:
        type: integer
      example: 1234
    UserId:
      name: user_id
      in: path
      description: The unique ID of the user
      required: true
      schema:
        type: integer
      example: 1234
    UserSegmentId:
      name: user_segment_id
      in: path
      description: The unique ID of the user segment
      required: true
      schema:
        type: integer
      example: 1234
    VoteId:
      name: vote_id
      in: path
      description: The unique ID of the vote
      required: true
      schema:
        type: integer
      example: 35467
  examples:
    ArticleAttachmentResponseExample:
      value:
        article_attachment:
          article_id: 23
          content_type: application/jpeg
          content_url: https://company.zendesk.com/hc/article_attachments/200109629/logo.jpg
          file_name: logo.jpg
          id: 1428
          inline: true
          locale: en_us
          size: 1428
    ArticleAttachmentsResponseExample:
      value:
        article_attachments:
          - article_id: 23
            content_type: application/jpeg
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/logo.jpg
            file_name: logo.jpg
            id: 1428
            inline: true
            size: 1428
          - article_id: 23
            content_type: application/pdf
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/party_invitation.pdf
            file_name: party_invitation.pdf
            id: 2857
            inline: false
            size: 58298
    ArticleLabelResponseExample:
      value:
        label:
          created_at: "2012-04-04T09:14:57Z"
          id: 2003
          name: instructions
          updated_at: "2012-04-04T09:14:57Z"
          url: https://{subdomain}.zendesk.com/api/v2/help_center/en-us/articles/labels/42.json
    ArticleLabelsResponseExample:
      value:
        labels:
          - created_at: "2012-04-04T09:14:57Z"
            id: 2003
            name: instructions
            updated_at: "2012-04-04T09:14:57Z"
            url: https://{subdomain}.zendesk.com/api/v2/help_center/articles/labels/42.json
    ArticleRequestExample:
      value:
        article:
          body: Use a tripod
          locale: en-us
          permission_group_id: 56
          title: Taking photos in low light
          user_segment_id: 123
        notify_subscribers: false
    ArticleResponseExample:
      value:
        article:
          author_id: 3465
          comments_disabled: true
          content_tag_ids:
            - 01GT23D51Y
            - 01GT23FWWN
          id: 37486578
          locale: en_us
          permission_group_id: 123
          position: 42
          promoted: false
          title: Article title
          user_segment_id: 12
    ArticleSearchResponseExample:
      value:
        results:
          - author_id: 888887
            draft: false
            id: 35467
            locale: en
            permission_group_id: 123
            title: Printing orders
            user_segment_id: 12
    ArticleSubscriptionResponseExample:
      value:
        subscription:
          content_id: 8748733
          id: 35467
          locale: en
          user_id: 888887
    ArticleSubscriptionsResponseExample:
      value:
        subscriptions:
          - content_id: 8748733
            id: 35467
            locale: en
            user_id: 888887
    ArticleUpVoteResponseExample:
      value:
        vote:
          id: 37486578
          value: 1
    ArticlesResponseExample:
      value:
        articles:
          - author_id: 888887
            draft: true
            id: 35467
            locale: en
            permission_group_id: 123
            title: Article title
            user_segment_id: 12
    BadRequestCreateSection:
      value:
        errors:
          parent_section_id:
            - cannot be assigned non-null value on this Guide plan
    BadRequestCreateUserSegment:
      value:
        errors:
          user_type:
            - value `foo` invalid; must be either `staff` or `signed_in_users`
    BadRequestUpdateSection:
      value:
        errors:
          parent_section_id:
            - would result in a cycle
    BadRequestUpdateUserSegment:
      value:
        errors:
          user_type:
            - value `foo` invalid; must be either `staff` or `signed_in_users`
    BlockArticleAttachmentsResponseExample:
      value:
        article_attachments:
          - article_id: 23
            content_type: application/pdf
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/logo.pdf
            file_name: logo.pdf
            id: 1428
            inline: false
            size: 1428
          - article_id: 23
            content_type: application/msword
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/results.doc
            file_name: results.doc
            id: 2857
            inline: false
            size: 234
    CategoriesResponseExample:
      value:
        categories:
          - description: This category contains a collection of Super Hero tricks
            id: 37486578
            locale: en-us
            name: Super Hero Tricks
          - description: All the cool tricks!
            id: 354675463
            locale: en-us
            name: Tips & Tricks
    CategoryResponse:
      value:
        category:
          description: This category contains a collection of Super Hero tricks
          id: 37486578
          locale: en-us
          name: Super Hero Tricks
          position: 2
    CategoryResponseExample:
      value:
        category:
          description: This category contains a collection of Super Hero tricks
          id: 37486578
          locale: en-us
          name: Super Hero Tricks
    CommentResponseExample:
      value:
        comment:
          author_id: 89567
          body: Good info!
          id: 35467
          locale: en
    CommentsResponseExample:
      value:
        comments:
          - author_id: 89567
            body: My printer is on fire
            id: 35467
            locale: en
          - author_id: 89589
            body: My printer is on fire too!
            id: 36221
            locale: en
    CommunityPostSearchResponseExample:
      value:
        results:
          - author_id: 4333787
            id: 4212256
            title: How do I make a return?
    ContentSubscriptionsResponseExample:
      value:
        subscriptions:
          - content_id: 8748733
            content_type: Article
            id: 35467
            locale: en
            user_id: 888887
    CreateuserImageResponseExample:
      value:
        user_image:
          content_type: image/jpeg
          path: /hc/user_images/Bvj4bPDuRd-7d5hFVszvmQ.jpeg
          size: 169846
    InlineArticleAttachmentsResponseExample:
      value:
        article_attachments:
          - article_id: 23
            content_type: application/jpeg
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/logo.jpg
            file_name: logo.jpg
            id: 1428
            inline: true
            size: 1428
          - article_id: 23
            content_type: application/gif
            content_url: https://company.zendesk.com/hc/article_attachments/200109629/footer.gif
            file_name: footer.gif
            id: 2857
            inline: true
            locale: en_us
            size: 234
    LocalesWithDefaultResponseExample:
      value:
        default_locale: it-it
        locales:
          - de-de
          - en-uk
          - en-us
          - es-419
          - es-es
          - fr-fr
          - it-it
          - ja-jp
          - pt-br
    MissingTranslationsResponseExample:
      value:
        locales:
          - en-us
          - da-dk
    PostCommentResponseExample:
      value:
        comment:
          author_id: 89567
          body: <p>I love my new non-flammable printer!</p>
          id: 35467
    PostCommentsResponseExample:
      value:
        comments:
          - author_id: 89567
            body: My printer is on fire!
            id: 35467
          - author_id: 89589
            body: My printer is on fire too!
            id: 36221
    PostResponseExample:
      value:
        post:
          author_id: 888887
          content_tag_ids:
            - 6776
            - 4545
          featured: true
          id: 35467
          title: Post title
    PostSubscriptionResponseExample:
      value:
        subscription:
          content_id: 8748733
          id: 35467
          locale: en
          user_id: 888887
    PostSubscriptionsResponseExample:
      value:
        subscriptions:
          - content_id: 8748733
            id: 35467
            locale: en
            user_id: 888887
    PostsResponseExample:
      value:
        posts:
          - id: 35467
            title: How do I open the safe
    RequestUserImageUploadResponseExample:
      value:
        upload:
          headers:
            Content-Disposition: attachment; filename="01F1D8HVJ3TK6CZH8HM51YEQRG.jpeg"
            Content-Type: image/jpeg
            X-Amz-Server-Side-Encryption: AES256
          token: 01F1D8HVJ3TK6CZH8HM51YEQRG
          url: https://{subdomain}.zendesk.com.com/aus-uploaded-assets/1/42/01F1D8HVJ3TK6CZH8HM51YEQRG?Content-Type=image%2Fjpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ACCESSKEY%2F20210322%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210322T152346Z&X-Amz-Expires=3600&X-Amz-Signature=a5fd09fb179fe3dc3e085398423988f1c5fc5f6a6eb66a0c020905f47b72f11b&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256
    SectionResponseExample:
      value:
        section:
          description: This section contains articles on flight instruments
          id: 3457836
          locale: en-us
          name: Avionics
          position: 2
    SectionSubscriptionResponseExample:
      value:
        subscription:
          content_id: 8748733
          id: 35467
          locale: en
          user_id: 888887
    SectionSubscriptionsResponseExample:
      value:
        subscriptions:
          - content_id: 8748733
            id: 35467
            locale: en
            user_id: 888887
    SectionsResponseExample:
      value:
        sections:
          - category_id: 888887
            description: This section contains articles on flight instruments
            id: 35467
            locale: en-us
            name: Avionics
          - category_id: 887285
            description: This section contains weather resources for pilots
            id: 36169
            locale: en-us
            name: Weather
    SessionResponseExample:
      value:
        current_session:
          csrf_token: 2hYE_3L80UfRteoLN1Z1eDA06lmzHlSyS
    TopicResponseExample:
      value:
        topic:
          description: Security Best Practices
          id: 35467
          name: Help Center-Tricks
    TopicSubscriptionResponseExample:
      value:
        subscription:
          content_id: 8748733
          id: 35467
          locale: en
          user_id: 888887
    TopicSubscriptionsResponseExample:
      value:
        subscriptions:
          - content_id: 8748733
            id: 35467
            locale: en
            user_id: 888887
    TopicsResponseExample:
      value:
        topics:
          - html_url: https://{subdomain}.zendesk.com/hc/en-us/community/topics/10-Using-Help-Center-Tips-Tricks
            id: 10
            name: Using Help Center - Tips & Tricks
            url: https://{subdomain}.zendesk.com/api/v2/community/topics/10.json
          - html_url: https://{subdomain}.zendesk.com/hc/en-us/community/topics/11-Using-Help-Center-Getting-Started-Guide
            id: 11
            name: Using Help Center - Getting Started Guide
            url: https://{subdomain}.zendesk.com/api/v2/community/topics/11.json
    TranslationResponseExample:
      value:
        translation:
          id: 634578
          locale: en-us
          source_id: 348756
          source_type: Article
          title: How to take pictures in low light
    TranslationsResponseExample:
      value:
        translations:
          - id: 634578
            locale: en-us
            outdated: true
            source_id: 348756
            source_type: Article
            title: Translation title
    UnifiedSearchResponseExample:
      value:
        meta:
          after_cursor: WzEuMCwxNjld
          before_cursor: WzEuMCwxNjhd
          has_more: true
        results:
          - title: How to make fish stew
            type: ARTICLE
            updated_at: "2021-10-11T15:02:22Z"
            url: http://example.zendesk.com/hc/en-us/articles/38393937-How-to-make-fish-stew
          - title: Latest updates on fish stew
            type: EXTERNAL_RECORD
            updated_at: "2021-11-12T15:02:22Z"
            url: http://example.com/blog/fish-stew-latest
    UserSegmentResponseExample:
      value:
        user_segment:
          built_in: false
          created_at: "2017-05-21T20:01:12Z"
          group_ids:
            - 12
          id: 7284
          name: VIP agents
          or_tags: []
          organization_ids: []
          tags:
            - vip
          updated_at: "2017-05-21T20:01:12Z"
          user_type: staff
    UserSegmentSectionsResponseExample:
      value:
        sections:
          - html_url: https://{subdomain}.zendesk.com/hc/en/sections/3242-A-section-
            id: 3242
            locale: en
            name: A section
            url: https://{subdomain}.zendesk.com/api/v2/help_center/en/sections/3242-A-section-.json
          - html_url: https://{subdomain}.zendesk.com/hc/en/sections/7352-Another-section-
            id: 7352
            locale: en
            name: Another section
            url: https://{subdomain}.zendesk.com/api/v2/help_center/en/sections/7352-Another-section-.json
    UserSegmentTopicsResponseExample:
      value:
        topics:
          - html_url: https://{subdomain}.zendesk.com/hc/en/community/topics/9273-A-topic-
            id: 9273
            name: A topic
            url: https://{subdomain}.zendesk.com/api/v2/community/topics/9273.json
          - html_url: https://{subdomain}.zendesk.com/hc/en/community/topics/2292-Another-topic-
            id: 2292
            name: Another topic
            url: https://{subdomain}.zendesk.com/api/v2/community/topics/2292-Another-topic-.json
    UserSegmentsResponseExample:
      value:
        user_segments:
          - built_in: false
            created_at: "2017-05-21T20:01:12Z"
            group_ids:
              - 12
            id: 7284
            name: VIP agents
            or_tags: []
            organization_ids: []
            tags:
              - vip
            updated_at: "2017-06-30T01:00:25Z"
            user_type: staff
          - built_in: false
            created_at: "2017-04-09T15:33:11Z"
            group_ids: []
            id: 9930
            name: Privileged users
            or_tags: []
            organization_ids:
              - 42
            tags: []
            updated_at: "2017-08-10T18:41:01Z"
            user_type: signed_in_users
    UserSubscriptionsResponseExample:
      value:
        user_subscriptions:
          - followed_id: 8748733
            follower_id: 398452
            id: 35467
    UserVotesResponseExample:
      value:
        votes:
          - id: 35467
            user_id: 888887
            value: -1
    VoteResponseExample:
      value:
        vote:
          id: 35467
          user_id: 888887
          value: -1
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
