Gladly Answer Management API

openapi: 3.2.0
info:
  title: Gladly Answer Management 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: Answer Management
  description: 'The **Answer Management API** allows you to create, update, and delete Answers in Gladly. To create an Answer with content, two calls would be needed.

    One call to create an Answer and subsequent call(s) to add content(s)'
paths:
  /api/v1/answers:
    post:
      tags:
      - Answer Management
      summary: Add Answer
      description: Adds an answer to the list of answers.
      operationId: addAnswer
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  type: string
                  description: unique answer id - optional (a new id will be generated if not provided)
                  example: 1grfSzATQLa334VDLCWc4A
                name:
                  type: string
                  description: Customer facing answer name
                  example: How to reset your password
                description:
                  type: string
                  description: Answer description gives more information about the answer to the Agent and appears in Answers Search when an Agent searches for an email or messaging answer. Only available for email and messaging content types
                  example: This is my first answer
                audienceIds:
                  type: array
                  items:
                    type: string
                  description: List of Audience IDs to be associated with the answer
                  example:
                  - audience-1
                  - audience-2
            examples:
              Sample Answer:
                summary: Example of an Answer
                value:
                  name: How to reset your password
                  description: This is my first answer
                  audienceIds:
                  - audience-1
                  - audience-2
      responses:
        '200':
          description: Added answer
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    description: answer id
                    example: 1grfSzATQLa334VDLCWc4A
                  name:
                    type: string
                    description: Customer facing answer name
                    example: How to reset your password
                  description:
                    type: string
                    description: Answer description (visible in the UI for only certain content types)
                    example: This is my first answer
                  audienceIds:
                    type: array
                    items:
                      type: string
                    description: List of Audience IDs associated with the answer
                    example:
                    - audience-1
                    - audience-2
                  createdAt:
                    type: string
                    format: RFC3339
                    description: Time the answer was added
                    example: '2024-06-13T15:16:29.894Z'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              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
                name too long:
                  value:
                    errors:
                    - attr: name
                      code: too_long
                      detail: name cannot be longer than 500 characters
                description too long:
                  value:
                    errors:
                    - attr: description
                      code: too_long
                      detail: description cannot be longer than 10000 characters
        '409':
          description: Specified id is in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                answer id already taken:
                  value:
                    errors:
                    - attr: id
                      code: taken
                      detail: answer id already taken
                name already taken:
                  value:
                    errors:
                    - attr: name
                      code: taken
                      detail: duplicate answer name
  /api/v1/answers/{answerId}:
    get:
      tags:
      - Answer Management
      summary: Get Answer
      description: Returns the answer requested.
      operationId: getAnswerById
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      responses:
        '200':
          description: answer
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    description: answer id
                    example: 1grfSzATQLa334VDLCWc4A
                  name:
                    type: string
                    description: Customer facing answer name
                    example: How to reset your password
                  description:
                    type: string
                    description: Answer description (visible in the UI for only certain content types)
                    example: This is my first answer
                  audienceIds:
                    type: array
                    items:
                      type: string
                    description: List of Audience IDs associated with the answer
                    example:
                    - audience-1
                    - audience-2
                  updatedAt:
                    type: string
                    format: RFC3339
                    description: Time the answer was last modified
                    example: '2024-06-13T15:16:29.894Z'
                  createdAt:
                    type: string
                    format: RFC3339
                    description: Time the answer was added
                    example: '2024-06-13T15:16:29.894Z'
        '404':
          description: Answer does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                  code: not_exist
                  detail: answer does not exist
    patch:
      tags:
      - Answer Management
      summary: Update Answer
      description: Updates the answer with the provided id.
      operationId: updateAnswer
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: Customer facing answer name
                  example: How to reset your password
                description:
                  type: string
                  description: Answer description gives more information about the answer to the Agent and appears in Answers Search when an Agent searches for an email or messaging answer. Only available for email and messaging content types
                  example: This is my first answer
                audienceIds:
                  type: array
                  items:
                    type: string
                  description: List of Audience IDs to be associated with the answer. Updating this will replace the existing set of audience IDs. The Audience API can be used to retrieve the audience IDs created for the org.
                  example:
                  - audience-1
                  - audience-2
            examples:
              Sample Answer:
                $ref: '#/paths/~1api~1v1~1answers/post/requestBody/content/application~1json/examples/Sample%20Answer'
      responses:
        '204':
          description: Answer updated
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                name already taken:
                  value:
                    errors:
                    - attr: name
                      code: taken
                      detail: duplicate answer name
                name too long:
                  value:
                    errors:
                    - attr: name
                      code: too_long
                      detail: name cannot be longer than 500 characters
                description too long:
                  value:
                    errors:
                    - attr: description
                      code: too_long
                      detail: description cannot be longer than 10000 characters
        '404':
          description: Answer does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                  code: not_exist
                  detail: answer does not exist
    delete:
      tags:
      - Answer Management
      summary: Delete Answer
      description: Deletes the answer with the provided id.
      operationId: deleteAnswer
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      responses:
        '204':
          description: Answer deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorsWithMeta'
              examples:
                answer associated with rules:
                  value:
                    errors:
                    - attr: answer
                      code: in_use
                      detail: answer is associated with rules
                answer associated with help center:
                  value:
                    errors:
                    - code: in_use
                      detail: Public response used in Help Center 'help center name' Section 'section name'
                      meta:
                        helpCenterID: helpCenterId
                        sectionID: sectionId
                        snippetID: answerId
                answer associated with thread:
                  value:
                    errors:
                    - attr: answer
                      code: in_use
                      detail: answer is associated with thread
        '404':
          description: Answer does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                  code: not_exist
                  detail: answer does not exist
  /api/v1/answers/{answerId}/languages/{language}/type/{type}:
    get:
      tags:
      - Answer Management
      summary: Get Answer Content
      description: Returns the answer content requested by language and type.
      operationId: getAnswerContentByLanguageAndType
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      - name: language
        in: path
        description: Language code according to ISO 639 format. The specified language must also be configured for the org.
        required: true
        schema:
          type: string
          example: en-us
      - name: type
        in: path
        description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
        required: true
        schema:
          type: string
          example: public
      responses:
        '200':
          description: answerContent
          content:
            application/json:
              schema:
                properties:
                  answerId:
                    type: string
                    description: answer id
                    example: 1grfSzATQLa334VDLCWc4A
                  language:
                    type: string
                    description: Language of the answer content
                    example: en-us
                  type:
                    type: string
                    description: Answer content type
                    example: public
                  bodyHtml:
                    type: string
                    description: The body of the answer content
                    example: <div>Public content</div>
                  title:
                    type: string
                    description: Title of the answer content. Present for `public` type.
                    example: Reset Password
                  subject:
                    type: string
                    description: Subject line of the answer content. Present for `email` type.
                    example: 'Re: Your inquiry'
                  internal:
                    type: boolean
                    description: Whether the content is internal-only. Present for `reference` type.
                    example: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid language:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: invalid language
                language not configured:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: language not configured for org
                invalid type:
                  value:
                    errors:
                    - attr: type
                      code: invalid
                      detail: invalid type
        '404':
          description: Answer content does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                answer content does not exist:
                  value:
                    errors:
                      code: not_exist
                      detail: answer content does not exist
                answer does not exist:
                  value:
                    errors:
                      code: not_exist
                      detail: answer does not exist
    put:
      tags:
      - Answer Management
      summary: Add or Update Answer Content
      description: Adds or Updates the answer content for the specified answer by language and type.
      operationId: addAnswerContentByLanguageAndType
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      - name: language
        in: path
        description: Language code according to ISO 639 format. The specified language must also be configured for the org.
        required: true
        schema:
          type: string
          example: en-us
      - name: type
        in: path
        description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
        required: true
        schema:
          type: string
          enum:
          - public
          - email
          - messaging
          - reference
          example: public
      requestBody:
        description: 'The request body fields depend on the content type:

          - **public**: `bodyHtml` (required), `title` (required)

          - **email**: `bodyHtml` (required), `subject` (required)

          - **messaging**: `bodyHtml` (required)

          - **reference**: `bodyHtml` (required), `internal` (optional, defaults to false)

          '
        content:
          application/json:
            schema:
              properties:
                bodyHtml:
                  type: string
                  description: The body of the answer content. Required for all content types.
                  example: <div>Public content</div>
                title:
                  type: string
                  description: Title of the answer content. Required for `public` type.
                  example: Reset Password
                subject:
                  type: string
                  description: Subject line of the answer content. Required for `email` type.
                  example: 'Re: Your inquiry'
                internal:
                  type: boolean
                  description: Whether the content is internal-only. Applicable to `reference` type.
                  example: false
            examples:
              Public Content:
                summary: Example of public answer content
                value:
                  bodyHtml: <div>Navigate to Settings and click Reset Password.</div>
                  title: How to reset your password
              Email Content:
                summary: Example of email answer content
                value:
                  bodyHtml: <div>Thank you for reaching out.</div>
                  subject: 'Re: Your inquiry'
              Messaging Content:
                summary: Example of messaging answer content
                value:
                  bodyHtml: <div>Thanks for messaging us!</div>
              Reference Content:
                summary: Example of reference answer content
                value:
                  bodyHtml: <div>Internal reference notes for agents.</div>
                  internal: false
      responses:
        '200':
          description: Added/Updated answer content
          content:
            application/json:
              schema:
                $ref: '#/paths/~1api~1v1~1answers~1%7BanswerId%7D~1languages~1%7Blanguage%7D~1type~1%7Btype%7D/get/responses/200/content/application~1json/schema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                invalid language:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: invalid language
                language not configured:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: language not configured for org
                invalid type:
                  value:
                    errors:
                    - attr: type
                      code: invalid
                      detail: invalid type
        '404':
          description: Answer does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                  code: not_exist
                  detail: answer does not exist
    delete:
      tags:
      - Answer Management
      summary: Delete Answer Content
      description: Deletes the answer content for the specified answer by language and type.
      operationId: deleteAnswerContentByLanguageAndType
      parameters:
      - name: answerId
        in: path
        description: id of the answer
        required: true
        schema:
          type: string
          example: 1grfSzATQLa334VDLCWc4A
      - name: language
        in: path
        description: Language code according to ISO 639 format. The specified language must also be configured for the org.
        required: true
        schema:
          type: string
          example: en-us
      - name: type
        in: path
        description: Type of answer. Must be one of `public`, `email`, `messaging`, or `reference`.
        required: true
        schema:
          type: string
          example: public
      responses:
        '204':
          description: Answer content deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Error'
                - $ref: '#/components/schemas/ErrorsWithMeta'
              examples:
                invalid language:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: invalid language
                language not configured:
                  value:
                    errors:
                    - attr: language
                      code: invalid
                      detail: language not configured for org
                invalid type:
                  value:
                    errors:
                    - attr: type
                      code: invalid
                      detail: invalid type
                type not implemented:
                  value:
                    errors:
                    - attr: type
                      code: invalid
                      detail: not implemented
                answer associated with rules:
                  value:
                    errors:
                    - attr: answer
                      code: in_use
                      detail: answer is associated with rules
                answer associated with help center:
                  value:
                    errors:
                    - code: in_use
                      detail: Public response used in Help Center 'help center name' Section 'section name'
                      meta:
                        helpCenterID: helpCenterId
                        sectionID: sectionId
                        snippetID: answerId
                answer associated with thread:
                  value:
                    errors:
                    - attr: answer
                      code: in_use
                      detail: answer is associated with thread
        '404':
          description: Does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                answer content does not exist:
                  value:
                    errors:
                      code: not_exist
                      detail: answer content does not exist
                answer does not exist:
                  value:
                    errors:
                      code: not_exist
                      detail: answer does not exist
components:
  schemas:
    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
    ErrorWithMeta:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          meta:
            type: object
            additionalProperties: true
            description: Additional information about the error
    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
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          example:
          - attr: content
            code: blank
            detail: content cannot be blank
  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