openapi: 3.0.3
info:
  description: <h1><b>Statusbrew Analytics API</b></h1>
    <p>The <a href="https://statusbrew.com" target="_blank">Statusbrew</a> Analytics API provides an externally accessible API for you to access your owned social profile analytics data so you can use that data to power BI dashboards, automate reporting, etc.
    </p>
    <br>
    <h1><b>Access Requirements & Authentication</b></h1>
    <p>Before accessing the Analytics API, you must obtain an access token. To do so, contact your Statusbrew's Account Manager.
    </p>
    <h3><b>Twitter Content End User License Agreement</b></h3>
    <p><b>Note -</b> Twitter has additional review and compliance requirements around exposing data through the Statusbrew Analytics API. You’re required to undergo a brief Twitter review and approval before being able to access their Twitter data through the Statusbrew Analytics API.
    <br><br>
      Contact your Statusbrew account manager to initiate the review process with Twitter. After Twitter approves your use case, the Account Owner needs to accept the Analytics API Twitter Content End User License Agreement.
    </p>
    <br>
    <h1><b>Analytics API Details</b></h1>
    <br>
    <h3><b>API URL</b></h3>
    <p><code>https://api.statusbrew.com</code></p>
    <br>
    <h3><b>Endpoints Overview</b></h3>
    <table>
      <thead>
        <tr>
          <th width="70%">Customer Endpoints</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><code>GET /v1/me</code></td>
          <td>Details of currently logged in User</td>
        </tr>
      </tbody>
    </table>
    <br>
    <table>
      <thead>
        <tr>
          <th width="70%">Space Endpoints</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><code>GET /v1/spaces</code></td>
          <td>Get a list of the available Spaces</td>
        </tr>
        <tr>
          <td><code>GET /v1/spaces/{space_id}/social_profiles</code></td>
          <td>Get a list of Social Profiles</td>
        </tr>
        <tr>
          <td><code>GET /v1/spaces/{space_id}/social_profile_groups</code></td>
          <td>Get a list of Social Profile Groups</td>
        </tr>
        <tr>
          <td><code>GET /v1/spaces/{space_id}/members</code></td>
          <td>Get a list of Users</td>
        </tr>
        <tr>
          <td><code>GET /v1/spaces/{space_id}/user_groups</code></td>
          <td>Get a list of User Groups</td>
        </tr>
        <tr>
          <td><code>GET /v1/spaces/{space_id}/tags</code></td>
          <td>Get a list of Tags</td>
        </tr>
      </tbody>
    </table>
    <br>
    <table>
      <thead>
        <tr>
          <th width="70%">Conversation Endpoints</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>
            <code>GET /v1/spaces/{space_id}/conversation_metric_events</code>
          </td>
          <td>Get a list of conversation metric events</td>
        </tr>
        <tr>
          <td>
            <code>GET /v1/spaces/{space_id}/conversation_activities</code>
          </td>
          <td>Get detail logs of activities on a conversation</td>
        </tr>
        <tr>
          <td>
            <code>GET /v1/spaces/{space_id}/conversations/{conversationId}</code>
          </td>
          <td>Get detail of a conversation</td>
        </tr>
      </tbody>
    </table>
      <br>
    <table>
      <thead>
        <tr>
          <th width="70%">Contact Endpoints</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>
            <code>GET /v1/spaces/{space_id}/contacts/{contact_id}</code>
          </td>
          <td>Get detail of a particular contact</td>
        </tr>
      </tbody>
    </table>
      <br>
    <table>
      <thead>
        <tr>
          <th width="70%">Analytics Endpoints</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>
            <code>POST /v1/spaces/{space_id}/insights</code>
          </td>
          <td>Get values of reporting insights</td>
        </tr>
      </tbody>
    </table>
    <br>
    <h3><b>General API Structure</b></h3>
    <p>All of the external API endpoints use the following naming structure -</p>
    <p><code>/{version}/spaces/{space_id}/{endpoint_path}</code></p>
    <p>Where -</p>
    <ul>
      <li><b>version</b> is the API major version number</li>
      <li><b>space_id</b> is your Statusbrew Space Id</li>
    </ul>
    <br>
    <h3><b>Versioning</b></h3>
    <p>The API is versioned using a MAJOR.MINOR version format.
    </p>
    <p>You can specify only the major number in requests, but the full version is included in responses.
    </p>
    <p>A major version represents a breaking change to the API, including updates to the syntax and semantics for making requests of the APIs and the syntax and semantics of the response of the API.
    </p>
    <p>A minor version represents a backwards compatible change to the API, such as adding new metrics, new endpoints, metric updates, etc. Minor versions are reflected in documentation, but not the API URL itself. Due to the backwards compatibility of minor versions, you only need to specify the major version in the URL path.
    </p>
    <h3><b>Rate Limits</b></h3>
    <p>The number of requests will be limited depending on your Space's current subscription plan.</p>
    <br>
    <h1><b>Endpoints</b></h1>
    <h3><b>Requests</b></h3>
    <p>All requests have the following format -</p>
    <h4><b>Request Headers</b></h4>
    <table>
      <thead>
        <tr>
          <th width="70%">Type</th>
          <th>Value</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>Authorization</td>
          <td>Bearer</td>
        </tr>
        <tr>
          <td>Accept</td>
          <td>application/json</td>
        </tr>
        <tr>
          <td>Content-Type</td>
          <td>application/json</td>
        </tr>
      </tbody>
    </table>
    <h4><b>Request Body</b></h4>
    <p>The content body for all data API requests are JSON objects. Details of the structure of that JSON object depend on the type of endpoint used.
    </p>
    <h3><b>Responses</b></h3>
    <p></p>
    <h4><b>HTTP Status Codes</b></h4>
    <p>The following HTTP status codes returned with the response have the following meanings -</p>
    <table>
      <thead>
        <tr>
          <th width="20%">Code</th>
          <th width="40%">Meaning</th>
          <th width="40%">Corrective Action</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>200 OK</td>
          <td>Request was processed successfully.</td>
          <td>None. You should be able to access the result of the request in the response body.</td>
        </tr>
        <tr>
          <td>400 Bad Request</td>
          <td>The request is malformed and does not conform with the request bodies specified in this document.</td>
          <td>Update the request body.</td>
        </tr>
        <tr>
          <td>401 Unauthorized</td>
          <td>The request does not contain a valid access token or that access token has expired.</td>
          <td>Reauthenticate and obtain a fresh token.</td>
        </tr>
        <tr>
          <td>403 Forbidden</td>
          <td>The request is accessing customer or profile data that the client is not allowed access to.</td>
          <td>Update the request body.</td>
        </tr>
        <tr>
          <td>404 Not Found</td>
          <td>The client is requesting an endpoint that does not exist.</td>
          <td>Check your endpoint, and use an existing endpoint.</td>
        </tr>
        <tr>
          <td>405 Method Not Allowed</td>
          <td>The client is using an HTTP verb that is not appropriate.</td>
          <td>Use the HTTP verb listed for the API endpoint you’re using; typically POST or GET. See the specific endpoint documentation for details.</td>
        </tr>
        <tr>
          <td>415 Unsupoported Media Type</td>
          <td>The client has submitted a request body that is not JSON or is requesting a response that is not JSON</td>
          <td>Correct the Accept and Content-Type headers to use jSON.</td>
        </tr>
        <tr>
          <td>429 Too Many Requests</td>
          <td>The client is making requests too quickly or has exhausted the allowed requests in a month.</td>
          <td>Slow down your requests.</td>
        </tr>
        <tr>
          <td>500 Internal Server Error</td>
          <td>The server had an issue processing the request.</td>
          <td>Retry the request. If this code persists, contact support.</td>
        </tr>
        <tr>
          <td>503 Service Unavailable</td>
          <td>The server is overloaded and cannot process the request.</td>
          <td>Retry the request. If this code persists, contact support.</td>
        </tr>
        <tr>
          <td>504 Gateway Timeout</td>
          <td>The server was unable to produce a result in time.</td>
          <td>Retry the request. If this code persists, contact support or decrease the scope of the request (smaller date ranges, less profiles, etc.).</td>
        </tr>
      </tbody>
    </table>
    <h4><b>Response Headers</b></h4>
    <p>The following headers are returned with each response -</p>
     <table>
        <thead>
          <tr>
            <th width="25%">Header</th>
            <th width="55%">Description</th>
            <th width="20%">Sample Value</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>X-Brew-API-Version</td>
            <td>Major and minor version of the response</td>
            <td>1.1</td>
          </tr>
          <tr>
            <td>X-Brew-Server-Version</td>
            <td>Server version, including the major, minor, and build number. The major and minor version reflect the latest available version of the API.</td>
            <td>1.1.3018</td>
          </tr>
        </tbody>
      </table>
  version: 1.0.0
  title: Analytics API
  contact:
    email: dev@statusbrew.com
servers:
  - url: 'https://api.statusbrew.com/v1'
security:
  - bearerAuth: []
tags:
  - name: Root User
  - name: Space
  - name: Social Profiles
  - name: Social Profile Groups
  - name: Users
  - name: User Groups
  - name: Tags
  - name: Conversation
  - name: Contact
  - name: Reports
paths:
  '/me':
    get:
      tags:
        - Root User
      description: <p>Fetch the details of the current logged in user.</p>
      operationId: fetchMe
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RootUser'
  '/spaces':
    get:
      tags:
        - Space
      operationId: fetchSpaces
      description: <p>Statusbrew Space is a workspace which holds all the information about social profiles along with its users who have access to that space.</p>
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Space'
  '/spaces/{space_id}/social_profiles':
    get:
      tags:
        - Social Profiles
      description: <p>Social Profile means any of the social media network profiles which currently can be managed with Statusbrew. Social profiles can be of the following types -
          <table>
            <thead>
              <th width="30%">Type</th>
              <th width="70%">Description</th>
            </thead>
            <tbody>
              <tr>
                <td>fb_page/td>
                <td>Facebook Page</td>
              </tr>
              <tr>
                <td>tw_profile</td>
                <td>Twitter Profile</td>
              </tr>
              <tr>
                <td>fb_ig_business</td>
                <td>Instagram Business Profile</td>
              </tr>
              <tr>
                <td>fb_page_backed_ig</td>
                <td>Facebook Page Backed Instagram Account</td>
              </tr>
              <tr>
                <td>li_company</td>
                <td>LinkedIn Company Page</td>
              </tr>
              <tr>
                <td>li_showcase</td>
                <td>LinkedIn Showcase Page</td>
              </tr>
              <tr>
                <td>gmb_location</td>
                <td>Google My Business Page</td>
              </tr>
              <tr>
                <td>yt_channel</td>
                <td>YouTube Profile (channel)</td>
              </tr>
            </tbody>
          </table>
        </p>
        <p><b>Note - </b>You may choose to ignore any extra fields returned in the API result.</p>
      operationId: fetchSocialProfiles
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialProfile'
  '/spaces/{space_id}/social_profile_groups':
    get:
      tags:
        - Social Profile Groups
      description: <p>Social Profile Group is a collection of any number of Social Profiles connected within a Space.</p>
        <p><b>Note - </b>You may choose to ignore any extra fields returned in the API result.</p>
      operationId: fetchSocialProfileGroups
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialProfileGroup'
  '/spaces/{space_id}/members':
    get:
      tags:
        - Users
      description: <p>Users refer to your social team that has been granted access to collaborate and manage your Social Profiles in a Space.<p>
        <p><b>Note - </b>You may choose to ignore any extra fields returned in the API result.</p>
      operationId: fetchUsers
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  '/spaces/{space_id}/user_groups':
    get:
      tags:
        - User Groups
      operationId: fetchUserGroups
      description: <p>User Group is a collection of any number of Users having access to a Space.</p>
        <p><b>Note - </b>You may choose to ignore any extra fields returned in the API result.</p>
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
  '/spaces/{space_id}/tags':
    get:
      description: <p>Tags in Statusbrew helps you to categorize the outbound and inbound content.</p>
        <p><b>Note - </b>You may choose to ignore any extra fields returned in the API result.</p>
      tags:
        - Tags
      operationId: fetchTags
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tag'
  '/spaces/{space_id}/conversation_metric_events':
    get:
      tags:
        - Conversation
      operationId: fetchConversationMetricEvents
      description: <p>Fetch list of conversation metric events. <a href="https://support.statusbrew.com/hc/en-us/articles/4414549860121-Conversation-Metric-Events" target="_blank">Learn more.</a></p>
        <h4><b>Request Parameters</b></h4>
         <table>
          <thead>
            <tr>
              <th width="10%">Parameter</th>
              <th width="45%">Type</th>
              <th width="45%">Description</th>
            </tr>
          </thead>
          <tbody>
             <tr>
              <td>startAt</td>
              <td><code>string</code></td>
              <td><i>Optional.</i><br>Start timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>endAt</td>
              <td><code>string</code></td>
              <td><i>Optional.</i><br>End timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>conversationId</td>
              <td><code>string</code></td>
              <td><i>Optional.</i></td>
            </tr>
             <tr>
              <td>metric</td>
              <td><code>string</code></td>
              <td><i>Optional.</i><br>Supported values - close_time, end_time</td>
            </tr>
            <tr>
              <td>skip</td>
              <td><code>integer</code></td>
              <td><i>Optional</i><br>To fetch next set of events</td>
            </tr>
            <tr>
              <td>limit</td>
              <td><code>integer</code></td>
              <td><i>Optional.</i><br>Number of events that can be fetch in a single request. Maximum value is 5000</td>
            </tr>
          </tbody>
        </table>
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
        - name: startAt
          in: query
          description: Start date
          required: false
          schema:
            type: string
        - name: endAt
          in: query
          description: End date
          required: false
          schema:
            type: string
        - name: conversationId
          in: query
          description: Conversation Id
          required: false
          schema:
            type: string
        - name: metric
          in: query
          description: Conversation Metric
          required: false
          schema:
            type: string
        - name: skip
          in: query
          description: Skip
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Limit
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: successful operation
  '/spaces/{space_id}/conversation_activities':
    get:
      tags:
        - Conversation
      operationId: fetchConversationActivities
      description: <p>Fetch detail logs of activities on a conversation.</p>
        <h4><b>Request Parameters</b></h4>
         <table>
          <thead>
            <tr>
              <th width="10%">Parameter</th>
              <th width="45%">Type</th>
              <th width="45%">Description</th>
            </tr>
          </thead>
          <tbody>
             <tr>
              <td>startAt</td>
              <td><code>string</code></td>
              <td><i>Optional.</i><br>Start timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>endAt</td>
              <td><code>string</code></td>
              <td><i>Optional.</i><br>End timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>conversationId</td>
              <td><code>string</code></td>
              <td><i>Optional.</i></td>
            </tr>
            <tr>
              <td>skip</td>
              <td><code>integer</code></td>
              <td><i>Optional</i><br>To fetch next set of activities</td>
            </tr>
            <tr>
              <td>limit</td>
              <td><code>integer</code></td>
              <td><i>Optional.</i><br>Number of activities that can be fetch in a single request. Maximum value is 5000</td>
            </tr>
          </tbody>
        </table>
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
        - name: startAt
          in: query
          description: Start date
          required: false
          schema:
            type: string
        - name: endAt
          in: query
          description: End date
          required: false
          schema:
            type: string
        - name: conversationId
          in: query
          description: Conversation Id
          required: false
          schema:
            type: string
        - name: skip
          in: query
          description: Skip
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Limit
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: successful operation
  '/spaces/{space_id}/conversations/{conversationId}':
    get:
      tags:
        - Conversation
      operationId: fetchConversationResource
      description: Fetch details of a conversation
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
        - name: conversationId
          in: path
          description: Conversation Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
  '/spaces/{space_id}/contact/{contact_id}':
    get:
      tags:
        - Contact
      operationId: fetchContactDetails
      description: Fetch detail of a particular contact
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
        - name: contact_id
          in: path
          description: Contact Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
  '/spaces/{space_id}/insights':
    post:
      description: <p>Fetch insights based on total conversations received, tagged, replied or closed.</p>
        <h4><b>Request Body</b></h4>
         <table>
          <thead>
            <tr>
              <th width="10%">Parameter</th>
              <th width="45%">Type</th>
              <th width="45%">Description</th>
            </tr>
          </thead>
          <tbody>
             <tr>
              <td>startTime</td>
              <td><code>integer</code></td>
              <td><b>Required.</b><br>Start timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>endTime</td>
              <td><code>integer</code></td>
              <td><b>Required.</b><br>End timestamp in seconds <i>(10 digit value)</i></td>
            </tr>
            <tr>
              <td>metrics</td>
              <td><code>{ "name:" "string", "key:" "string", "aggFunction:" "string }[]<code></td>
              <td><b>Required.</b><br>Individual measurements related to the insights data provided by the social network or computed by Statusbrew</td>
            </tr>
            <tr>
              <td>dimensions</td>
              <td><code>{ "name:" "string", "groupType:" "string" }[]</code></td>
              <td><i>Optional</i><br>Dimensions are common criteria that are used to aggregate data, such as the date on which an action occurred or the language in which the conversations are being received. Each row of data has a unique combination of dimension values. The dimensions you choose for a report determine how Statusbrew calculates the values for the metrics in that report.</td>
            </tr>
            <tr>
              <td>filters</td>
              <td><code>{ "name:" "string", "values:" ["string"] }[]</code></td>
              <td><i>Optional.</i><br>Filter the exported data based on your requirement</td>
            </tr>
          </tbody>
        </table>
      tags:
        - Reports
      operationId: fetchInsights
      parameters:
        - name: space_id
          in: path
          description: Current selected space
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/InsightsBody'
      responses:
        '200':
          description: successful operation
#          content:
#            application/json:
#              schema:
#                $ref: '#/components/schemas/InsightsResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    RootUser:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    Space:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              isLocked:
                type: boolean
                description: "Returns true if the Social Profiles or Users count in the Space exceeds the current subscription plan."
    SocialProfile:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              externalName:
                type: string
              type:
                type: string
                enum: [fb_page, gmb_location, fb_page_backed_ig, fb_ig_business, li_company, li_showcase, tw_profile, yt_channel]
              socialNetwork:
                type: string
                enum: [facebook, twitter, instagram, google_my_business, linkedin, youtube]
    SocialProfileGroup:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              socialProfiles:
                type: array
                items:
                  type: string
    InsightsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              value:
                type: object
                properties:
                  value:
                    type: object
                    properties:
                      total:
                        type: integer
                        nullable: true
                      totalCloseTimeInSec:
                        type: integer
                        nullable: true
                      totalReplyTimeInSec:
                        type: integer
                        nullable: true
              dimensions:
                type: object
                properties:
                  reportingInterval:
                    type: string
                    nullable: true
                    format: date
                  hourOfday:
                    type: integer
                    description: Value ranges from 0 - 23 representing the hour of the day.
                    nullable: true
                  dayOfWeek:
                    type: integer
                    description: Value ranges from 1 - 7 representing the days of the week. Week starts from Sunday.
                    nullable: true
                  socialProfile:
                    type: string
                    nullable: true
                  actor:
                    type: string
                    nullable: true
    User:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              user:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
              spaceId:
                type: string
              isActive:
                type: boolean
                description: "Returns false if the User is archived"
    UserGroup:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              users:
                type: array
                items:
                  type: string
    Tag:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              color:
                type: string
              isActive:
                type: boolean
                description: "Returns false if the Tag is archived"
  requestBodies:
    InsightsBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              startTime:
                description: Start timestamp (in seconds, 10 digit value)
                type: integer
              endTime:
                description: End timestamp (in seconds, 10 digit value)
                type: integer
              filters:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    values:
                      type: array
                      items:
                        type: string
              dimensions:
                type: array
                items:
                  properties:
                    name:
                      type: string
                    groupType:
                      type: string
              metrics:
                type: array
                items:
                  properties:
                    name:
                      type: string
                    key:
                      type: string
                    aggFunction:
                      type: string
