Gladly Topics API

openapi: 3.2.0
info:
  title: Gladly Topics API
  version: '1.0'
  description: '# Introducing the Gladly API


    At Gladly, we believe that customer service is best when it''s a conversation.'
servers:
- url: https://{organization}.gladly.com/api/v1
  description: Production
  variables:
    organization:
      default: organization
      description: Your Gladly organization subdomain
- url: https://{organization}.gladly.qa/api/v1
  description: Sandbox
  variables:
    organization:
      default: organization
      description: Your Gladly QA organization subdomain
security:
- basicAuth: []
tags:
- name: Topics
  description: 'A **Topic** is a way of labeling a conversation in Gladly for specific business purposes. For example, an agent may apply the topic "Return" to a conversation where a customer returns merchandise.

    Topics are used for reporting and to control various workflows.


    Topics can be configured to have a nested hierarchy. For instance, the topic "Return" could be a parent of "Size" and "Color" child topics. Visit our Help Pages to learn more about Hierarchical Topics.'
paths:
  /api/v1/topics:
    get:
      tags:
      - Topics
      summary: List Topics
      description: Returns a list of Topics.
      operationId: getTopics
      responses:
        '200':
          description: Topics
          content:
            application/json:
              schema:
                title: Topics
                type: array
                items:
                  $ref: '#/paths/~1api~1v1~1topics~1%7BtopicId%7D/get/responses/200/content/application~1json/schema'
              example:
                summary: Topics
                value:
                - id: Z_Oto7j-Sy2DlQdnZBDdDw
                  disabled: false
                  name: Order Return
                - id: 8eiDakrnTgKa3HIxtgV5OA
                  disabled: false
                  name: Damaged Merchandise
                  parentId: Z_Oto7j-Sy2DlQdnZBDdDw
                - id: WgZnWNicSMmORcNzP8rwGQ
                  disabled: true
                  name: Holiday 2019
                  parentId: Z_Oto7j-Sy2DlQdnZBDdDw
    post:
      tags:
      - Topics
      summary: Add Topic
      description: Add a Topic to the list of available Topics.
      operationId: addTopic
      requestBody:
        description: Topic to create
        content:
          application/json:
            schema:
              title: Add Topic Request
              required:
              - name
              properties:
                id:
                  type: string
                  description: unique Topic id - optional (a new id will be generated if not provided)
                  example: uu4t00vITaKQ3bVjU2UrGQ
                name:
                  type: string
                  description: Name of the Topic - must be unique
                  example: Order Returns
                disabled:
                  type: boolean
                  description: If the Topic is not in use - optional, defaults to **false**
                  example: false
                parentId:
                  type: string
                  description: id of parent Topic, if the Topic is nested under another topic - optional
                  example: ChefeoTHSlaIbKg57H5R9Q
      responses:
        '201':
          description: Topic Created
          headers:
            Location:
              schema: null
              type: string
              description: path to the created Topic
              example: /api/v1/topics/RgEZdEiUSSK9DBjYFQLQyQ
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
              examples:
                id contains unsupported characters:
                  value:
                    errors:
                    - attr: id
                      code: invalid
                      detail: id contains unsupported characters
                name cannot be blank or missing:
                  value:
                    errors:
                    - attr: name
                      code: blank
                      detail: name cannot be blank
        '409':
          description: Topic contains conflicting values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsWithMeta'
              examples:
                topic with specified id already exists:
                  value:
                    errors:
                    - attr: id
                      code: taken
                      detail: the topic with specified id already exists
                another topic already has this name:
                  value:
                    errors:
                    - attr: name
                      code: taken
                      detail: another topic already has this name
                      meta:
                        id: BgMCrCVbTrGhAeDTwIr44g
  /api/v1/topics/{topicId}:
    parameters:
    - name: topicId
      in: path
      description: id of the Topic
      required: true
      schema:
        type: string
        example: uu4t00vITaKQ3bVjU2UrGQ
    get:
      tags:
      - Topics
      summary: Get Topic
      description: Get a Topic by its unique id.
      operationId: getTopic
      responses:
        '200':
          description: Topic
          content:
            application/json:
              schema:
                title: Topic
                type: object
                properties:
                  id:
                    type: string
                    description: Id of the Topic
                    example: uu4t00vITaKQ3bVjU2UrGQ
                  name:
                    type: string
                    description: Name of the Topic
                    example: Order Returns
                  disabled:
                    type: boolean
                    description: If the Topic cannot be applied to Conversations, and is no longer in use
                    example: false
                  parentId:
                    type: string
                    description: If the Topic is nested under another topic, parentId is the Id of the parent topic. For more information about topic hierarchy, please visit the [help docs](https://help.gladly.com/docs/en/principles-of-hierarchical-topics)
                    example: ChefeoTHSlaIbKg57H5R9Q
        '404':
          description: Given Topic id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
    patch:
      tags:
      - Topics
      summary: Update Topic
      description: Update an existing Topic.
      operationId: updateTopic
      requestBody:
        content:
          application/json:
            schema:
              title: Update Topic Request
              required:
              - name
              properties:
                name:
                  type: string
                  description: Name of the Topic
                  example: Order Returns
                disabled:
                  type: boolean
                  description: If the Topic is not in use
                  example: false
                parentId:
                  type: string
                  description: id of parent Topic, if the Topic is nested under another topic - optional
                  example: ChefeoTHSlaIbKg57H5R9Q
      responses:
        '204':
          description: Topic updated successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                name cannot be blank or missing:
                  value:
                    errors:
                    - attr: name
                      code: blank
                      detail: name cannot be blank
        '404':
          description: Topic with the specified id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrors'
              example:
                errors:
                  code: not_exist
                  detail: conversation topic [topicId] does not exist
        '409':
          description: Topic update contains conflicting values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsWithMeta'
              examples:
                another topic already has this name:
                  value:
                    errors:
                    - attr: name
                      code: taken
                      detail: another topic already has this name
                      meta:
                        id: BgMCrCVbTrGhAeDTwIr44g
components:
  schemas:
    ErrorWithMeta:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          meta:
            type: object
            additionalProperties: true
            description: Additional information about the error
    NotFoundErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - code: not_exist
            detail: entity does not exist
    ErrorsWithMeta:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorWithMeta'
          example:
          - attr: name
            code: taken
            detail: another entity with this name already exists
            meta:
              id: conflicting-id
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
    Error:
      type: object
      properties:
        attr:
          type: string
          description: Identifies the field causing the error
        code:
          type: string
          description: Code indicating the error type
        detail:
          type: string
          description: More details describing what went wrong
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Gladly API uses token-based **Basic Authentication**. API tokens are associated with designated Gladly users.

        To create and use an API token, your user must have the API User permission. An API token can be used to perform any API request without restriction.


        | user name   | password  |

        | ----------- | --------- |

        | agent email | API token |


        The credentials must be passed via an `Authorization` HTTP header. All requests must be made over HTTPS.


        ```shell

        curl -u user@organization.com:$GLADLY_API_TOKEN \

        https://organization.gladly.com/api/v1/organization

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth — username is the API user email; password is the API token. Requires the "API User" permission.
x-tagGroups:
- name: REST API
  tags:
  - Agents
  - Public Answer
  - Answer Management
  - Audiences
  - Business Hours
  - Communications
  - Conversations
  - Customers
  - Events
  - Export
  - Freeform Topics
  - Inboxes
  - Organization
  - Proactive Conversations
  - Reports
  - Tasks
  - Teams
  - User Identity
  - Topics
  - Webhooks
- name: Webhooks
  tags:
  - Summary
  - Payloads
- name: Lookup API
  tags:
  - Customer Lookup
- name: Resources
  tags:
  - Versioning
  - Error Handling
  - Rate Limit
  - Rich Content
  - Launching Soon