openapi: 3.0.2
info:
  title: Conversocial Agent Workspace Data API
  termsOfService: https://www.verint.com/our-company/legal-documents/verintcom-terms-of-service/
  license:
    name: Verint Master Customer Agreement
    url: https://www.verint.com/our-company/legal-documents/master-agreement/
  contact:
    name: Conversocial Support
    url: https://support.conversocial.com
    email: support@conversocial.com
  # Verint Connect values
  x-vc-product_code: cnvs-aw-data-api
  x-vc-product_suite: cnvs
  x-vc-app-id-uri: https://not-available-yet/
  description: |-
    The Conversocial Agent Workspace Customer API is the primary way for clients to access the rich set of data curated by Conversocial

    ## Authentication

    Authentication is performed using HTTP basic authentication. The username field should contain the token name, and the password field should contain the token secret. Tokens can be generated (and their secrets reset) using the [Conversocial Agent Workspace web app](http://app.conversocial.com). Tokens are associated with a set of "roles" (permission sets) in the same way as users are. Token roles can be customised using the web app. If a token does not possess an appropriate permission to perform an action (including reads) an HTTP 403 response will be returned. Tokens are subject to usage limits and an HTTP 429 error response will be returned if the limits are exceeded. Responses are returned as JSON.

    ## Making requests

    __Responses__

    The response body is JSON by default. HTTP status codes are used to differentiate successful requests from error conditions.

    A successful request will send a HTTP status of 200

    ```json
    {
      "accounts": [{
           "url": "https://api.conversocial.com/v1.3/accounts/14054",
           "id": "14054"
         }],
      "paging": {
               "next_page": null,
               "prev_page": null
      }
    }
    ```

    An unsuccessful request will return a HTTP status code and any error specifics will be returned in the `error_code` or `param` properties of the JSON response.

    ```json
    {
      "status": "error",
      "message": "No such author",
      "http_status": "404 Object Not Found"
    }
    ```

    ## Additional request data
    __Returning additional information with the `fields` parameter__<br />
    On most requests it is possible to filter the returned `fields` by using the fields query parameter. For example, the query parameter `fields=url,first_name,id` would exclude all fields returned except for the three specified.

    This can be used to include entities information that isn't supplied by default; For example, when searching for a channel you can pull back the channel's `name` as part of the query. It can also be used to shrink response size by specifying only the required fields for responses which return a list of all fields by default. If an unknown field name is specified then it is skipped without error.

    __Filter information using the `fields` parameter__<br />
    On certain requests it is possible to filter matched entities by a field value. This is done by specifying query arguments. Query arguments can be repeated, in which case entities that match any value are returned - for example, to select channels 6, 9 and 14 the query parameters `id=6&id=14&id=9` could be used.

    __Each resource details its possible fields__

    ## Searching
    It is possible to search for a range of items between two dates. For instance, requestion the conversations started between the 1st October 2014 and the 14th October 2014 would require `oldest_sort_date_gte=2014-10-01&oldest_sort_date_lte=2014-10-14`
    Inequality searches are used to return a range of data.

    ## Sorting
    Responses can be sorted with a `sort` query parameter. Each endpoint supports a number of `fields` that can be used for sorting. `sort=id` will sort entities by the ID field, `sort=-date_from` will sort items by `date_from` from youngest to oldest. Sort fields can be stacked, as in `sort=-date_from,-date_to` will sort reverse by `date_from` and then by `date_to` where `date_from` values are equal.

    Entity IDs are strings and are unique only within an entity class - account "2" and channel "2" can both exist and are not the related.

    ## Other operations
    Checking if a field is set to a non-null value can be done with `_isnull` - `generated_date_isnull=1` will find reports without a `generated_date` set, and `generated_date_isnull=0` will find reports where a `generated_date` has been set

    ## Pagination (v1.3+)
    Queries can be paginated using the `prev_page` and `next_page` object properties returned by a suitable request. The number of items returned can be changed using the URL parameter `page_size` e.g `https://api.conversocial.com/v1.3/conversations?is_priorty=false&page_size=10`

    ## Date Formats
    All dates and times stated in API responses are given in "Coordinated Universal Time", (UTC). These times can be converted to your local timezone after you receive the response. A time field will be formatted as follows `2013-11-18T11:20:24`

    ## Rate Limiting
    Rate limiting is performed per token, e.g. the username and password combination will be restricted to a maximum of 30 requests per minute

  version: 1.3.1
externalDocs:
  description: Legacy Documentation
  url: https://api-docs.conversocial.com/landing/index.html
servers:
  - url: https://api.conversocial.com/v1.3
    description: Default
  - url: "{scheme}://{host}/{path}"
    description: Dynamic
    variables:
      scheme:
        enum:
        - http
        - https
        default: https
      host:
        default: api.conversocial.com
      path:
        default: v1.3
tags:
  - name: Accounts
    description: Account info
  - name: Authors
    description: Access to Author info
  - name: Channels
    description: Get data about Channels
  - name: Conversations
    description: Everything about your Conversations
  - name: Queues
    description: Get data about Queues
  - name: Reports
    description: Operations about Reports
  - name: Tags
    description: Operations about Tags
  - name: Teams
    description: Operations about Teams
  - name: Users
    description: Get User info

components:
  securitySchemes:
    basicAuth:
      description: |-
        [Provision and manage API credentials in the Agent Workspace application](https://app.conversocial.com/account/api/#/).
      type: http
      scheme: basic

  schemas:
    Paging:
      type: object
      properties:
        next_page:
          type: string
          nullable: true
        prev_page:
          type: string
          nullable: true
      required:
        - next_page

    AccountBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: string
          example: "5487"
        url:
          type: string
          example: https://api.conversocial.com/v1.3/accounts/5487

    Account:
      allOf:
        - $ref: "#/components/schemas/AccountBase"
        - properties:
            channels:
              type: array
              items:
                $ref: "#/components/schemas/ChannelBase"
            created_date:
              type: string
              example: "2024-09-21T17:19:20.294004"
            description:
              type: string
              nullable: true
            name:
              type: string
              example: "Enterprise Domain"
            package:
              type: string
              example: "Enterprise"
            reports:
              type: string
              example: https://api.conversocial.com/v1.3/reports?account=5487

    AccountsResponse:
      type: object
      required:
        - accounts
      properties:
        accounts:
          type: array
          items:
            $ref: "#/components/schemas/Account"
        paging:
          $ref: "#/components/schemas/Paging"

    Action:
      type: object
      properties:
        conversation:
          $ref: "#/components/schemas/ConversationBase"
        channels:
          type: array
          items:
            $ref: "#/components/schemas/ChannelBase"
        actioned_by:
          $ref: "#/components/schemas/UserBase"
        approval_status:
          type: string
          nullable: true
        approved_by:
          $ref: "#/components/schemas/UserBase"
        approved_date:
          type: string
          nullable: true
          example: "2024-10-13 18:33:25"
        content_id:
          type: string
          nullable: true
        created_date:
          type: string
          example: "2024-10-11 01:45:01"
        id:
          type: string
          example: 6167267599e7ff1fbf9953db
        performed_date:
          type: string
          example: "2024-10-13 18:32:10"
        queue:
          properties:
            id:
              type: string
              example: 614a141d886b9345d37a5815
          type: object
        rejection_message:
          type: string
          nullable: true
        successful:
          type: boolean
        type:
          type: string
          example: "addtag"
        warnings:
          type: string
          nullable: true

    AuthorBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: string
          example: "f:1563548099"
        url:
          type: string
          example: "https://api.conversocial.com/v1.3/authors/f:1563548099"

    Author:
      allOf:
        - $ref: "#/components/schemas/AuthorBase"
        - properties:
            description:
              type: string
              nullable: true
            location:
              type: string
              nullable: true
            platform_namespace:
              type: string
              example: "f"
            platform:
              type: string
              example: facebook
              nullable: true
            platform_id:
              type: string
              example: "1563548099"
            profile_link:
              type: string
              example: hhttp://www.facebook.com/bob.loblaw
            profile_picture:
              type: string
              example: https://graph.facebook.com/1563548099/picture?type=square
            real_name:
              type: string
              example: Robert Loblaw
              nullable: true
            screen_name:
              type: string
              example: bob.loblaw
              nullable: true
            website:
              type: string
              nullable: true

    AuthorsResponse:
      type: object
      required:
        - authors
      properties:
        authors:
          type: array
          items:
            $ref: "#/components/schemas/Author"

    AuthorResponse:
      type: object
      required:
        - author
      properties:
        author:
          $ref: "#/components/schemas/Author"

    ChannelBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: integer
          example: 71589
        url:
          type: string
          example: https://api.conversocial.com/v1.3/channels/71589

    ChannelEmbedded:
      # This object is embedded into Conversation responses
      allOf:
        - $ref: "#/components/schemas/ChannelBase"
        - properties:
            name:
              type: string
              example: "@careprint"
            platform_id:
              type: string
              example: "16560043"

    Channel:
      allOf:
        - $ref: "#/components/schemas/ChannelBase"
        - properties:
            account:
              type: array
              items:
                $ref: "#/components/schemas/AccountBase"
            created:
              type: string
              example: "2024-09-23T14:43:43.334909"
            fans:
              type: string
              example: "34453"
            fb_page_url:
              type: string
              nullable: true
            is_active:
              type: boolean
            name:
              type: string
              example: "@test_timemachinecompany1"
            reports:
              type: string
              example: "https://api.conversocial.com/v1.3/reports?channel=71589"
            small_image:
              type: string
              nullable: true
            type:
              type: string
              example: instagram

    ChannelsResponse:
      type: object
      properties:
        channels:
          type: array
          items:
            $ref: "#/components/schemas/Channel"
        paging:
          $ref: "#/components/schemas/Paging"

    ChannelResponse:
      type: object
      properties:
        channel:
          $ref: "#/components/schemas/Channel"

    ContentAttachments:
      type: object
      oneOf:
        - $ref: "#/components/schemas/ContentAttachmentsTwitter"

    ContentAttachmentsTwitter:
      type: object
      properties:
        description:
          type: string
        caption:
          type: string
        href:
          type: string
        name:
          type: string
        properties:
          type: array
          items:
            type: string
        media:
          type: array
          items:
            $ref: "#/components/schemas/MediaAttachmentTwitter"

    MediaAttachmentTwitter:
      type: object
      properties:
        src:
          type: string
        alt:
          type: string
        href:
          type: string

    Sentiment:
      type: object
      properties:
        created_by:
            $ref: "#/components/schemas/UserBase"
        value:
          type: integer
          example: 1
          description: "1 for positive, 0 for negative"

    Content:
      type: object
      properties:
        channels:
          type: array
          items:
            $ref: "#/components/schemas/ChannelEmbedded"
        author:
          $ref: "#/components/schemas/AuthorBase"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/TagBase"
        attachments:
            $ref: "#/components/schemas/ContentAttachments"
        created_date:
          type: string
          example: "2024-10-13T12:12:38"
          description: "Note that this value is set to 1970-01-01T00:00:00 for Twitter content."
        id:
          type: string
          example: 6166cd3a7cfb0e608b20b5ee
        imported_date:
          type: string
          example: "2024-10-13T12:12:42.346"
        imported_delta:
          type: integer
          example: 4
        is_by_source:
          type: boolean
        is_priority:
          type: boolean
        is_private:
          type: boolean
        link:
          type: string
          nullable: true
          example: "http://www.facebook.com/9898141441/messages/"
          description: "Note that this value is not available for Twitter content."
        parent:
          type: string
          example: "62124276769f9aa0a80c13a8"
          description: "ID of parent content item when content is threaded"
        platform:
          type: string
          example: twitter
        platform_id:
          type: string
          example: "AUlEOjE3ODQxNDQ4NTk1MzQxMzA1OjM0MDI4MjM2Njg0MTcxMDMwMDk0O"
        sentiment:
          $ref: "#/components/schemas/Sentiment"
        text:
          type: string
          example: "Content message text, if any"
          description: "Note that this value is not available for Twitter content."
        type:
          type: string
          example: InstagramMessage

    HandlingTimes:
      type: array
      items:
        type: object
        properties:
          handling_time:
            type: integer
            description: Handling time in seconds
          interaction_time:
            type: integer
            description: Interaction time in seconds
          user:
            $ref: "#/components/schemas/UserBase"

    ConversationBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: string
          example: "6166cd3a559f41e9a8feb87a"
        url:
          type: string
          example: "https://api.conversocial.com/v1.3/conversations/6166cd3a559f41e9a8feb87a"

    Conversation:
      type: object
      properties:
        author:
          $ref: "#/components/schemas/AuthorBase"
        channels:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/ChannelBase"
              - properties:
                  name:
                    type: string
                    example: "@bobloblaw"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/TagBase"
        content_ids:
          type: array
          items:
            type: string
          example: ["6166c2f643813ad3626da4c5","6166c2f643813ad3626da4c4"]
        assigned_to:
          $ref: "#/components/schemas/UserBase"
        close_reason:
          type: string
          nullable: true
          example: "Resolved"
        contains_private:
          type: boolean
        handling_times:
          $ref: "#/components/schemas/HandlingTimes"
        id:
          type: string
          example: "61641900559f41e9a8feb7d2"
        is_priority:
          type: boolean
        status:
          type: string
          example: "assigned"
        url:
          type: string
          example: "https://app.conversocial.com/v1.3/conversations/61641900559f41e9a8feb7d2"

    ConversationPatchRequest:
      type: object
      properties:
        status:
          description: |-
            A new status for the conversation.
          type: string
          enum: [on_hold, closing]
        tag_ids:
          description: |-
            A list of active Tag IDs. Existing list of tags will be overwritten, not merged. <br/>
            Tags must already exist.<br/>
          type: array
          items:
            type: integer
          example: [1,5,283]
        close_reason:
          description: |-
            A string representing the close reason. The Close Reason must already exist.
          type: string
          example: Resolved

    ConversationsResponse:
      type: object
      properties:
        paging:
          $ref: "#/components/schemas/Paging"
        content:
          type: array
          items:
            $ref: "#/components/schemas/Content"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
        conversations:
          type: array
          items:
            $ref: "#/components/schemas/Conversation"
        notes:
          type: array
          items:
            $ref: "#/components/schemas/Note"

    ConversationResponse:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/Content"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/Action"
        notes:
          type: array
          items:
            $ref: "#/components/schemas/Note"
        conversation:
          $ref: "#/components/schemas/Conversation"

    Note:
      type: object
      properties:
        created_by:
          $ref: "#/components/schemas/UserBase"
        conversation:
          $ref: "#/components/schemas/ConversationBase"
        content_id:
          type: string
          example: 6166e38d599bade9ed7cb201
        created_date:
          type: string
          example: "2024-11-03T13:16:14.058"
        id:
          type: string
          example: "61828b9edb5071854a8125cd"
        is_deleted:
          type: boolean
        text:
          type: string
          example: "User tried phoning call centre on 2024-03-02"

    QueueBase:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          example: 614a141d886b9345d37a5815

    Queue:
      allOf:
        - $ref: "#/components/schemas/QueueBase"
        - properties:
            external_id:
              type: string
              nullable: true
            is_active:
              type: boolean
            name:
              type: string
              example: "* Default"
            rank:
              type: string
              example: "9"
            role:
              type: string
              example: default
            url:
              type: string
              example: https://api.conversocial.com/v1.3/queues/614a141d886b9345d37a5815

    QueuesResponse:
      type: object
      properties:
        queues:
          type: array
          items:
            $ref: "#/components/schemas/Queue"
        paging:
          $ref: "#/components/schemas/Paging"

    QueueResponse:
      type: object
      properties:
        queue:
          $ref: "#/components/schemas/Queue"

    ReportBase:
      type: object
      properties:
        id:
          type: string
        url:
          type: string

    Report:
      allOf:
        - $ref: "#/components/schemas/ReportBase"
        - properties:
            account:
              $ref: "#/components/schemas/AccountBase"
            name:
              type: string
            generation_start_date:
              type: string
              nullable: true
            generated_by:
              $ref: "#/components/schemas/UserBase"
            generated_date:
              type: string
            failure:
              type: string
            download:
              type: string
            date_from:
              type: string
            date_to:
              type: string
            date_type:
              type: string
              enum:
                - created_date
                - updated_date

    ReportsResponse:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: "#/components/schemas/Report"
        paging:
          $ref: "#/components/schemas/Paging"

    ReportResponse:
      type: object
      properties:
        report:
          $ref: "#/components/schemas/Report"

    # A base request schema for Report creation via POST
    ReportBasePostRequest:
      type: object
      properties:
        date_from:
          type: string
          example: "2024-01-05"
          description: |-
            The start of the date range to generate the report for. Information for this date will be included in the report.
        date_to:
          type: string
          example: "2024-02-05"
          description: |-
            The end of the date range to generate the report for. Information for this date will be included in the report.
        date_type:
          type: string
          enum:
            - created_date
            - updated_date
          example: "created_date"
          description: |-
            The type of date to match the date_from and date_to against.

    # Report creation via POST for an Account
    ReportAccountPostRequest:
      allOf:
        - $ref: "#/components/schemas/ReportBasePostRequest"
        - type: object
          properties:
            account:
              type: integer
              example: 7864
              description: |-
                The ID of the account to generate the report for. Must be specified only if "channel" is not

    # Report creation via POST for a Channel
    ReportChannelPostRequest:
      allOf:
        - $ref: "#/components/schemas/ReportBasePostRequest"
        - type: object
          properties:
            channel:
              type: integer
              example: 5487
              description: |-
                The ID of the channel to generate the report for. Must be specified only if "account" is not

    ReportCreatedResponse:
      type: object
      properties:
        report:
          $ref: "#/components/schemas/ReportBase"

    TagBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: string
          example: "247"
        url:
          type: string
          example: https://api.conversocial.com/v1.3/tags/247

    Tag:
      allOf:
        - $ref: "#/components/schemas/TagBase"
        - type: object
          properties:
            name:
              type: string
              example: "VIP"
            is_active:
              type: boolean

    TagsResponse:
      type: object
      properties:
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        paging:
          $ref: "#/components/schemas/Paging"

    TagResponse:
      type: object
      properties:
        tag:
          $ref: "#/components/schemas/Tag"

    TeamBase:
      type: object
      required:
        - url
        - id
      properties:
        id:
          type: string
          example: "6182bf80db5071854a81261c"
        url:
          type: string
          example: https://api.conversocial.com/v1.3/teams/6182bf80db5071854a81261c

    Team:
      allOf:
        - $ref: "#/components/schemas/TeamBase"
        - type: object
          properties:
            name:
              type: string
              example: "Critical Care Team"
            account:
              $ref: "#/components/schemas/AccountBase"
            users:
              type: array
              items:
                $ref: "#/components/schemas/UserBase"

    TeamsResponse:
      type: object
      properties:
        teams:
          type: array
          items:
            $ref: "#/components/schemas/Team"
        paging:
          $ref: "#/components/schemas/Paging"

    TeamResponse:
      type: object
      properties:
        team:
          $ref: "#/components/schemas/Team"

    UserBase:
      type: object
      nullable: true
      properties:
        id:
          type: string
          example: "3468"
        url:
          type: string
          example: "https://api.conversocial.com/v1.3/users/3468"

    User:
      allOf:
        - $ref: "#/components/schemas/UserBase"
        - properties:
            date_joined:
              type: string
              example: "2024-11-03T16:57:18.529237"
            email:
              type: string
              example: "user@domain.com"
            first_name:
              type: string
              example: Robert
            id:
              type: string
              example: "9642"
            is_expert:
              type: boolean
              default: false
            last_login:
              type: string
              example: "2024-11-03T04:22:12.87154"
              nullable: true
            last_name:
              type: string
              example: Loblaw
            timezone:
              type: string
              example: "Europe/London"
            url:
              type: string
              example: "https://api.conversocial.com/v1.3/users/9642"

    UsersResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        paging:
          $ref: "#/components/schemas/Paging"

    UserResponse:
      type: object
      properties:
        user:
          $ref: "#/components/schemas/User"

    ### -- Error responses

    BaseErrorResponse:
      type: object
      required:
        - status
        - message
        - http_status
      properties:
        status:
          type: string
        message:
          type: string
        http_status:
          type: string

    BadRequestResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: Unknown object
            http_status: 400 Bad Request

    UnauthorizedResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: Not authenticated
            http_status: 401 Authentication Required

    ForbiddenResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: Credentials do not permit this action
            http_status: 403 Forbidden

    NotFoundResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: No such object
            http_status: 404 Not Found

    TooManyRequestsResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: Rate limit exceeded
            http_status: 429 Too many requests

    DefaultErrorResponse:
      allOf:
        - $ref: "#/components/schemas/BaseErrorResponse"
        - example:
            status: error
            message: Unknown Error
            http_status: 500 Error



  parameters:
    page_size:
      name: page_size
      in: query
      description: >
        The number of results to return. This value is capped at `50`.
      schema:
        type: integer
        default: 50

    account_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return only the `url` and `id` fields.<br/>
        Example: `fields=url,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            [
              url,
              reports,
              id,
              channels,
              description,
              package,
              created_date,
              name,
            ]
        minItems: 0
      style: form
      explode: false

    author_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return ALL fields.<br/>
        Example: `fields=url,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            [
              id,
              url,
              platform,
              platform_id,
              screen_name,
              real_name,
              location,
              website,
              description,
              profile_picture,
              profile_link,
            ]
        minItems: 0
      style: form
      explode: false

    channel_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return only the `url` and `id` fields when requesting a list of Channels and ALL data when requesting a single Channel.<br/>
        Example: `fields=url,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            [
              created,
              name,
              url,
              is_active,
              id,
              small_image,
              reports,
              fans,
              account,
              fb_page_url,
              type,
            ]
        minItems: 0
      style: form
      explode: false

    conversation_fields:
      name: fields
      in: query
      description: >
        Return additional data about the conversation.<br/>
        Example: `fields=url,reports,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            - channels
            - status
            - tags
            - is_priority
            - contains_private
            - assigned_to
            - author
            - url
            - handling_times
            - close_reason
        minItems: 0
      style: form
      explode: false

    conversation_include:
      name: include
      in: query
      description: >
        Use the `include` parameter to enrich the API response with additional data.<br/><br/>
        Notes, actions and content can be loaded in this manner.<br/><br/>
        To see the content of the messages that make up a conversation you must set `include=content` which will return an additional array of messages associated with the conversation or conversations in the request. <br/><br/>
        To side-load multiple aspects, specify multiple include parameters.<br/><br/>
        Example: `include=content&include=notes`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            - actions
            - notes
            - content
        minItems: 0
      style: form
      explode: true

    conversation_id:
      name: id
      in: path
      description: >
        The unique id of a conversation.<br/>
        <br/>
        Example: `52d7d44e56c02c17e96fe8b8`
      required: true
      schema:
        type: string

    queue_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return only the `id` and `url` fields when requesting a list and ALL fields when requesting a single Queue.<br/>
        Example: `fields=name,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum: [id, url, rank, name, is_active, role, external_id]
        minItems: 0
      style: form
      explode: false

    report_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return only the `id` and `url fields.<br/>
        Example: `fields=name,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            [
              name,
              generation_start_date,
              generated_by,
              date_type,
              date_from,
              date_to,
              failure,
              download,
            ]
        minItems: 0
      style: form
      explode: false

    tag_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return ALL fields.<br/>
        Example: `fields=name,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum: [id, name, url, is_active]
        minItems: 0
      style: form
      explode: false

    team_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return ALL fields.<br/>
        Example: `fields=name,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum: [name, id, account, users, url]
        minItems: 0
      style: form
      explode: false

    user_fields:
      name: fields
      in: query
      description: >
        Specify which data fields to return.<br/>
        If unset, the API will return ALL fields.<br/>
        Example: `fields=name,id`<br/>
      schema:
        type: array
        items:
          type: string
          enum:
            [
              id,
              first_name,
              last_name,
              timezone,
              date_joined,
              last_login,
              email,
              is_expert,
            ]
        minItems: 0
      style: form
      explode: false

security:
  - basicAuth: []

paths:
  /accounts:
    get:
      tags:
        - Accounts
      summary: Get data for one or more Accounts
      description: |-
        Lists the accounts that the access token can manipulate. In the current version of the API each token can only manipulate one account.<br/>
        This resource supports additional data through the fields parameter
      operationId: getAccounts
      parameters:
        - name: id
          description: >
            The unique id of an account or accounts to access
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            minItems: 1
          style: form
          explode: true
        # Do these filters even work?
        - name: name
          description: >
            The name of an account to access
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/account_fields"
        - name: created_date_gte
          description: >
            Filter results based on `created_date`
          in: query
          schema:
            type: string
        - name: created_date_gt
          description: >
            Filter results based on `created_date`
          in: query
          schema:
            type: string
        - name: created_date_lte
          description: >
            Filter results based on `created_date`
          in: query
          schema:
            type: string
        - name: created_date_lt
          description: >
            Filter results based on `created_date`
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /accounts/{id}:
    get:
      tags:
        - Accounts
      summary: Get data for one or more Accounts
      description: |-
        Lists the accounts that the access token can manipulate. In the current version of the API each token can only manipulate one account.<br/>
        This resource supports additional data through the fields parameter
      operationId: getAccountsById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            The unique id of an account to access
        - $ref: "#/components/parameters/account_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /authors:
    get:
      tags:
        - Authors
      summary: Get data for multiple Authors
      description: |-
        Information about multiple Social Media authors (e.g. a Twitter, Youtube or Instagram users) specified by ID. This resource supports specifying returned metadata through the fields parameter
      operationId: getAuthors
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
            minItems: 1
          style: form
          explode: false
          description: >
            A comma separated list of Conversocial author IDs
        - $ref: "#/components/parameters/author_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthorsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /authors/{id}:
    get:
      tags:
        - Authors
      summary: Get data for a single Author
      description: |-
        Information about a single Social Media author e.g. a Twitter, Youtube or Instagram user<br/><br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getAuthorById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A Conversocial author ID
        - $ref: "#/components/parameters/author_fields"

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /channels:
    get:
      tags:
        - Channels
      summary: Get data for multiple Channels
      description: |-
        Search for channels on the account(s) this token belongs to. By default returns just the channel ID and the channel details URL, but different fields may be selected if required.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getChannels
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: >
            An exact Channel name to match against
        - $ref: "#/components/parameters/channel_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /channels/{id}:
    get:
      tags:
        - Channels
      summary: Get data for a single Channel
      description: |-
        Information about one channel. Includes links to the account that the channel is part of, and a link to the reports generated on the channel data.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getChannelById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A Channel ID
        - $ref: "#/components/parameters/channel_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /conversations:
    get:
      tags:
        - Conversations
      summary: Get a list of Conversation objects
      description: >
        Returns a list of Conversation objects optionally filtered by parameters.<br/>
        This resource supports additional data through the `fields` parameter
      operationId: getConversations
      parameters:
        - $ref: "#/components/parameters/page_size"

        - name: sort
          in: query
          description: >
            The field to sort results by. Prefixing the field name with `-` will reverse the sort order.
          schema:
            type: string
            enum:
              - oldest_sort_date
              - -oldest_sort_date
              - newest_sort_date
              - -newest_sort_date
            default: -oldest_sort_date

        - name: is_priority
          in: query
          schema:
            type: boolean
            default: true
          description: >
            Whether a conversation has been prioritised by the Conversocial priority engine.<br/>
            Must be supplied if `status` is not.

        - name: status
          in: query
          schema:
            type: string
            enum:
              [
                archived,
                on_hold,
                closing,
                closed,
                pending_approval,
                unread,
                assigned,
              ]
          description: >
            The current Conversation status.<br/>
            Must be supplied if `is_priority` is not.

        - name: oldest_sort_date_gt
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose first message (the oldest message) falls after the supplied date.<br/>

            `oldest_sort_date` parameters must be supplied as a pair, e.g.: <br/>

            `?oldest_sort_date_gt=2014-01-01`<br/>
            `&oldest_sort_date_lt=2015-01-01`<br/><br/>

            Note that `oldest_sort_date` and `newest_sort_date` cannot be used at the same time.
        - name: oldest_sort_date_gte
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose first message (the oldest message) falls after or on the supplied date.
        - name: oldest_sort_date_lt
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose first message (the oldest message) falls before the supplied date.
        - name: oldest_sort_date_lte
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose first message (the oldest message) falls before or on the supplied date.

        - name: newest_sort_date_gt
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose last message (the most recent message) falls after the supplied date.<br/>

            `newest_sort_date` parameters must be supplied as a pair, e.g.: <br/>

            `?newest_sort_date_gte=2014-01-01`<br/>
            `&newest_sort_date_lte=2015-01-01`<br/><br/>

            Note that `oldest_sort_date` and `newest_sort_date` cannot be used at the same time.
        - name: newest_sort_date_gte
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose last message (the most recent message) falls on or after the supplied date.
        - name: newest_sort_date_lt
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose last message (the most recent message) falls before the supplied date.
        - name: newest_sort_date_lte
          in: query
          schema:
            type: string
            format: date
          description: >
            Conversations whose last message (the most recent message) falls before or on the supplied date.

        - name: channel
          in: query
          schema:
            type: integer
          description: >
            The unique id of a channel to retrieve conversations for
        - name: tag
          in: query
          schema:
            type: string
          description: >
            Filter Conversations by the tag assigned to it. Requires a Tag name (not ID).
        - name: contains_private
          in: query
          schema:
            type: boolean
          description: >
            Whether the conversations contain private messages, for instance Twitter DMs or Facebook messages
        - name: assigned_to
          in: query
          schema:
            type: integer
          description: >
            Filter Conversations by the user assigned to that Conversation.
        - name: author
          in: query
          schema:
            type: string
          description: >
            Filter Conversations by the Social Media or private messaging author of the Conversation.

        - $ref: "#/components/parameters/conversation_fields"

        - $ref: "#/components/parameters/conversation_include"

        - name: queue_id
          in: query
          schema:
            type: array
            items:
              type: string
            minItems: 1
          style: form
          explode: false
          description: >
            Filter conversations by Queue ID.<br/>
            You can specify multiple comma-separated values.<br/>
            Example: `queue_id=abc123456,xyz987654`<br/>

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationsResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /conversations/{id}:
    get:
      tags:
        - Conversations
      summary: Return a specific conversation
      description: |-
        Get data for a specific Conversation by ID.
      operationId: getConversationById
      parameters:
        - $ref: "#/components/parameters/conversation_id"
        - $ref: "#/components/parameters/conversation_fields"
        - $ref: "#/components/parameters/conversation_include"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "404":
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"
    patch:
      tags:
        - Conversations
      summary: Update a limited set of Conversation attributes
      description: |-
        Update a specific Conversation by ID. Note that only a few attributes are available for updates.
      operationId: patchConversationById
      parameters:
        - $ref: "#/components/parameters/conversation_id"
        - $ref: "#/components/parameters/conversation_fields"
        - $ref: "#/components/parameters/conversation_include"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ConversationPatchRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "404":
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /queues:
    get:
      tags:
        - Queues
      summary: Get data for multiple Queues
      description: |-
        Lists all of the queues present on this account.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getQueues
      parameters:
        - $ref: "#/components/parameters/queue_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueuesResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /queues/{id}:
    get:
      tags:
        - Queues
      summary: Get data for a single Channels
      description: |-
        Information about one queue.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getQueueById
      parameters:
        - name: id
          description: >
            A Queue ID. <br/>
            Note: If the Queue cannot be found, this method will return a list of all Queues.
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/queue_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /reports:
    get:
      tags:
        - Reports
      summary: Get data for multiple Reports
      description: |-
        Search for reports available on this token. Can be used in combination with the 'account' or 'channel' filters.
      operationId: getReports
      parameters:
        - name: account
          description: >
            The unique id of an account to retrieve reports for
          in: query
          schema:
            type: string
        - name: channel
          description: >
            The unique id of a channel to retrieve reports for
          in: query
          schema:
            type: string
        - $ref: "#/components/parameters/report_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"
    post:
      tags:
        - Reports
      summary: Create a new Report
      description: |-
        Create a new report for one account or one channel.<br/><br/>
        Either the `channel` or `account` values must be provided, along with the desired report date range (in the form of `date_from` and `date_to` fields. The `date_type` parameter specifies how the content items will be matched for report generation.
        <br/>

        Example request body:
        ```
        {
            "account": 123,
            "date_from": "2013-01-01",
            "date_to":"2013-01-31",
            "date_type":"created_date"
        }
        ```
      operationId: postReports
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ReportAccountPostRequest"
                - $ref: "#/components/schemas/ReportChannelPostRequest"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportCreatedResponse"
        "400":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /reports/{id}:
    get:
      tags:
        - Reports
      summary: Get data for a single Report
      description: |-
        Information about one report. Reports are initially queued onto a processing queue and have no `generation_start_date` or `download` attributes. Once generation starts the `generation_start_date` attribute appears. Once generation completes, a successful report will have `generated_date` and `download` attributes. On generation failure the `failure` attribute will contain a description of which phase of generation failed.

        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getReportById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A Report ID
        - $ref: "#/components/parameters/report_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"
  /tags:
    get:
      tags:
        - Tags
      summary: Get data for multiple Tags
      description: |-
        Lists all of the Tags present on this account.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getTags
      parameters:
        - $ref: "#/components/parameters/tag_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /tags/{id}:
    get:
      tags:
        - Tags
      summary: Get data for a single Tag
      description: |-
        Information about one Tag.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getTgById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A Tag ID
        - $ref: "#/components/parameters/tag_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /teams:
    get:
      tags:
        - Teams
      summary: Get data for multiple Teams
      description: |-
        Lists all of the teams present on this account.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getTeams
      parameters:
        - $ref: "#/components/parameters/team_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamsResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /teams/{id}:
    get:
      tags:
        - Teams
      summary: Get data for a single Team
      description: |-
        Information about one team.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getTeamById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A Team ID
        - $ref: "#/components/parameters/team_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /users:
    get:
      tags:
        - Users
      summary: Get data for multiple Users
      description: |-
        Lists all of the Users present on this account.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getUsers
      parameters:
        - $ref: "#/components/parameters/user_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"

  /users/{id}:
    get:
      tags:
        - Users
      summary: Get data for a single User
      description: |-
        Information about one User.
        <br/>
        This resource supports specifying returned metadata through the fields parameter
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >
            A User ID
        - $ref: "#/components/parameters/user_fields"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsResponse"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultErrorResponse"
