Guru Announcements API

openapi: 3.2.0
info:
  title: Guru Announcements API
  version: '1.0'
  description: 'Operations tagged Announcements across 2 of this provider''s published API definitions: guru-openapi.json, guru-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.getguru.com
- url: https://api.getguru.com/api/v1
  description: Guru production API
tags:
- name: Announcements
paths:
  /api/v1/announcements:
    get:
      operationId: get_announcements
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/KnowledgeAlertNotification'
                type: array
          description: successful operation
        '400':
          content: {}
          description: Invalid/Incomplete Request
        '401':
          content: {}
          description: Request was unauthorized
        '403':
          content: {}
          description: Forbidden access to the resource
        '404':
          content: {}
          description: Resource could not be found
      security:
      - basicAuth: []
      summary: Get Team Announcements
      tags:
      - Announcements
      x-roles:
      - read:announcements
    servers:
    - url: https://api.getguru.com
  /alerts/create:
    post:
      summary: Create announcement
      operationId: createAnnouncement
      tags:
      - Announcements
      responses:
        '201':
          description: Announcement created.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts:
    get:
      summary: List announcements
      operationId: listAnnouncements
      tags:
      - Announcements
      responses:
        '200':
          description: List of announcements.
      security:
      - basicAuth: []
      - bearerAuth: []
    delete:
      summary: Delete announcement
      operationId: deleteAnnouncement
      tags:
      - Announcements
      responses:
        '204':
          description: Announcement deleted.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/stats:
    get:
      summary: Get announcement stats
      operationId: getAnnouncementStats
      tags:
      - Announcements
      responses:
        '200':
          description: Announcement stats.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/stats-summary:
    get:
      summary: Get announcement stats summary
      operationId: getAnnouncementStatsSummary
      tags:
      - Announcements
      responses:
        '200':
          description: Announcement stats summary.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/user-stats:
    get:
      summary: Get announcement user stats
      operationId: getAnnouncementUserStats
      tags:
      - Announcements
      responses:
        '200':
          description: Announcement user stats.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/export-users:
    post:
      summary: Export announcement user details
      operationId: exportAnnouncementUsers
      tags:
      - Announcements
      responses:
        '200':
          description: Export started.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/send-reminders:
    post:
      summary: Send announcement reminders
      operationId: sendAnnouncementReminders
      tags:
      - Announcements
      responses:
        '200':
          description: Reminders sent.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
  /alerts/mark-read:
    put:
      summary: Mark announcement as read
      operationId: markAnnouncementRead
      tags:
      - Announcements
      responses:
        '200':
          description: Announcement marked as read.
      security:
      - basicAuth: []
      - bearerAuth: []
    servers:
    - url: https://api.getguru.com/api/v1
      description: Guru production API
components:
  schemas:
    FeaturedImageCandidateEntry:
      properties:
        id:
          type: string
        type:
          enum:
          - IMAGE
          - IFRAME
          - VIDEO
          type: string
        cropSpec:
          $ref: '#/components/schemas/ImageCropSpec'
        signedUrl:
          type: string
        url:
          type: string
        width:
          format: int32
          type: integer
        height:
          format: int32
          type: integer
      type: object
    Card:
      description: The Card is the basic unit of knowledge in Guru
      properties:
        id:
          description: ID of the Card
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        content:
          description: The Card's HTML or Markdown content
          example: Here's some **awesome content**
          type: string
        owner:
          $ref: '#/components/schemas/User'
        lastModified:
          description: Date the Card was last modified
          format: date-time
          readOnly: true
          type: string
        version:
          description: Current version of the Card. As the card gets updated and revised, the version number will increase.
          example: 1
          format: int32
          readOnly: true
          type: integer
        verificationState:
          description: Whether the card is TRUSTED, STALE, or NEEDS_VERIFICATION
          enum:
          - TRUSTED
          - STALE
          - NEEDS_VERIFICATION
          - SYNCED_NO_VERIFICATION
          type: string
        collection:
          $ref: '#/components/schemas/CollectionModel'
        teamId:
          description: If the card shareType is TEAM, this is the ID of the Team that it is shared with
          readOnly: true
          type: string
        attachments:
          description: Attachments to the card
          items:
            $ref: '#/components/schemas/CardAttachment'
          type: array
        boards:
          description: Returns Board objects that this card appears on
          items:
            $ref: '#/components/schemas/Board'
          type: array
          uniqueItems: true
        dateCreated:
          description: Date the Card was created
          format: date-time
          readOnly: true
          type: string
        shareStatus:
          description: The share status of the Card. TEAM for team shared cards and PRIVATE for privately shared cards
          enum:
          - TEAM
          - PRIVATE
          - PUBLIC
          example: TEAM
          type: string
        lastVerified:
          description: Date the Card was last verified
          format: date-time
          type: string
        lastVerifiedBy:
          $ref: '#/components/schemas/User'
        lastModifiedBy:
          $ref: '#/components/schemas/User'
        preferredPhrase:
          description: The title of the Card
          example: My New Card
          type: string
        slug:
          description: The slug is the URL address to the card
          example: https://app.getguru.com/cards/:slug_goes_here
          readOnly: true
          type: string
        suppressVerification:
          description: Flag for enabling card verification on save
          type: boolean
        verificationInterval:
          description: Time interval (in days), indicating the frequency that this card needs re-verification. Passing in null will default to 30 days.
          format: int32
          type: integer
        verifiers:
          description: Users/Groups that are responsible for verifying this card
          items:
            $ref: '#/components/schemas/CardVerifier'
          type: array
        verificationType:
          description: Whether the card's verification date is ABSOLUTE or RELATIVE
          enum:
          - ABSOLUTE
          - RELATIVE
          type: string
        collaborators:
          description: Users/Groups that this card is explicitly shared to. Collaborators of a card are the only ones who have access if the Card's shareStatus is PRIVATE.
          items:
            $ref: '#/components/schemas/CardCollaborator'
          type: array
        favoritedDate:
          description: Date when this card has been favorited by the current user
          format: date-time
          readOnly: true
          type: string
        favorited:
          description: Whether this card has been favorited by the current user
          readOnly: true
          type: boolean
        publicLinkAllowed:
          type: boolean
        originalOwner:
          $ref: '#/components/schemas/User'
        lastViewed:
          description: Last time the card was viewed
          format: date-time
          readOnly: true
          type: string
        archived:
          description: Indicates if the Card has been archived
          readOnly: true
          type: boolean
        cardType:
          description: The type of the Card. CARD for content cards, FILE for file cards, QUESTION for Questions.
          enum:
          - FILE
          - CARD
          - QUESTION
          readOnly: true
          type: string
        verificationReason:
          description: Reason this card needs verification. UPDATE if this card was updated by a user that is not the verifier. NEW_VERIFIER if this card was assigned to a new verifier but has not yet been verified. This value will only be present if the verification state is NEEDS_VERIFICATION
          enum:
          - UPDATE
          - NEW_VERIFIER
          - QUESTION
          - REQUESTED
          - EXPIRED
          readOnly: true
          type: string
        verificationReasons:
          items:
            enum:
            - UPDATE
            - NEW_VERIFIER
            - QUESTION
            - REQUESTED
            - EXPIRED
            type: string
          type: array
        verificationInitiator:
          $ref: '#/components/schemas/User'
        nextVerificationDate:
          description: Next date that this Card needs verification dependent on verification interval
          format: date-time
          type: string
        commentCount:
          description: Number of comments on the card
          format: int32
          readOnly: true
          type: integer
        cardInfo:
          $ref: '#/components/schemas/CardInfo'
        syncInfo:
          $ref: '#/components/schemas/CardSyncInfo'
        verificationInitiationDate:
          description: Date corresponding to the action that unverified the card
          format: date-time
          type: string
        cardTemplateId:
          description: ID of the template from which this card was created if applicable
          readOnly: true
          type: string
        tags:
          description: Returns Tag objects associated with this card
          items:
            $ref: '#/components/schemas/Tag'
          type: array
          uniqueItems: true
      required:
      - content
      - preferredPhrase
      type: object
    KnowledgeAlertNotification:
      properties:
        creator:
          $ref: '#/components/schemas/User'
        card:
          $ref: '#/components/schemas/Card'
        alertId:
          type: string
        cardTitle:
          type: string
        dateSent:
          format: date-time
          type: string
        alertNote:
          type: string
        viewed:
          type: boolean
        collectionHexColor:
          type: string
        featuredImage:
          $ref: '#/components/schemas/FeaturedImageCandidateEntry'
        read:
          type: boolean
        groups:
          items:
            $ref: '#/components/schemas/UserGroup'
          type: array
      type: object
    CardCollaborator:
      discriminator:
        propertyName: type
        mappings:
          user: '#/components/schemas/UserCollaborator'
          user-group: '#/components/schemas/UserGroupCollaborator'
      properties:
        id:
          description: The ID (email address or group ID) of the collaborator
          type: string
        dateCreated:
          description: Date the collaborator was created
          format: date-time
          type: string
        removed:
          type: boolean
        type:
          enum:
          - user
          - user-group
          type: string
      required:
      - type
      type: object
    CollectionStats:
      properties:
        stats:
          additionalProperties:
            $ref: '#/components/schemas/Stats'
          description: Returns an object that includes the Collection Trust Score, and Card Count of the Collection.
          type: object
      type: object
    CardSyncInfo:
      properties:
        contentSyncType:
          enum:
          - ZENDESK
          - ZENDESK_IMPORT
          - CONFLUENCE
          - MANUAL
          - GOOGLE_DRIVE
          - ZENEFITS
          - BOX
          - KUSTOMER
          - DROPBOX
          - SALESFORCE
          - GURU
          type: string
        externalUrl:
          type: string
        lastSyncDate:
          format: date-time
          type: string
        lastUpdateDate:
          format: date-time
          type: string
      type: object
    CollectionModel:
      properties:
        name:
          description: Collection Name
          type: string
        readOnly:
          type: boolean
        id:
          description: ID of the collection
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        color:
          description: A hex value for the color of the Collection
          example: '#f44336'
          type: string
        deleted:
          description: Flag for whether this Collection has been deleted
          type: boolean
        defaultVerifier:
          type: string
        syncType:
          description: 'If this Collection has been synced, this will return the type. Types include: Zendesk, Confluence, Google Drive, and Manual.'
          enum:
          - ZENDESK
          - ZENDESK_IMPORT
          - CONFLUENCE
          - MANUAL
          - GOOGLE_DRIVE
          - ZENEFITS
          - BOX
          - KUSTOMER
          - DROPBOX
          - SALESFORCE
          - GURU
          type: string
        collectionType:
          description: The type can be either INTERNAL or EXTERNAL. EXTERNAL indicates that the card is from a synced Collection.
          enum:
          - INTERNAL
          - EXTERNAL
          type: string
        boards:
          description: Number of boards in this Collection
          format: int64
          type: integer
        dateCreated:
          description: Date the collection was created
          format: date-time
          type: string
        cards:
          description: Number of cards in this Collection
          format: int64
          type: integer
        slug:
          description: The slug is the URL to get to this Collection
          example: https://app.getguru.com/collections/:slug_goes_here
          type: string
        publicCardsEnabled:
          type: boolean
        collectionStats:
          $ref: '#/components/schemas/CollectionStats'
        syncVerificationEnabled:
          type: boolean
        collectionTypeDetail:
          description: The type can be FRAMEWORK, ONBOARDING, USER or EXTERNAL.
          enum:
          - ONBOARDING
          - FRAMEWORK
          - USER
          - EXTERNAL
          - WELCOME
          - ONBOARDING_UNEDITED
          type: string
        homeBoardSlug:
          type: string
        verificationInterval:
          format: int32
          type: integer
        administrator:
          type: boolean
        lastSyncedDate:
          description: The date that the Collection was last synced from the source
          format: date-time
          type: string
        emoji:
          type: string
        topLevelSyncLocation:
          description: The URL where the content of the Collection is being synced from
          type: string
        publicCards:
          format: int64
          type: integer
        madeByGuru:
          type: boolean
        description:
          description: Collection Description
          type: string
        tags:
          description: Returns all Tag objects associated with this collection
          format: int64
          type: integer
        token:
          type: string
      type: object
    CardVerifier:
      discriminator:
        propertyName: type
        mappings:
          user-group: '#/components/schemas/UserGroupVerifier'
          user: '#/components/schemas/UserVerifier'
      properties:
        id:
          description: ID of the verifier
          type: string
        dateCreated:
          description: 'Date the verifier was created. Dates are in ISO-8601 format. Example date (January 2nd 2014 12pm UTC): 2014-01-02T12:00:00.000+0000'
          format: date-time
          type: string
        type:
          enum:
          - user
          - user-group
          type: string
      required:
      - type
      type: object
    Board:
      properties:
        boardGroupId:
          description: The ID of the Board Group that this Board belongs to
          type: string
        removed:
          description: Boolean flag if this Board has been removed
          type: boolean
        defaultList:
          description: When this board is a users default favorite list
          type: boolean
        id:
          description: The ID of the directory
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        lastModified:
          description: The date that the directory was last modified
          format: date-time
          type: string
        groupsSharedWith:
          description: Returns the groups that a directory is shared with
          items:
            type: string
          type: array
        collection:
          $ref: '#/components/schemas/CollectionModel'
        lastModifiedBy:
          $ref: '#/components/schemas/User'
        slug:
          description: The slug is the URL address to the directory
          example: https://app.getguru.com/boards/:slug_goes_here
          type: string
        numberOfFacts:
          description: The number of cards in the directory
          format: int32
          type: integer
        favoritedDate:
          description: When this directory has been favorited by the current user
          format: date-time
          type: string
        favorited:
          description: Whether this board has been favorited by the current user
          type: boolean
        legacyType:
          enum:
          - BOARD_GROUP
          - BOARD
          - SECTION
          type: string
        description:
          description: An optional short description of the directory
          type: string
        items:
          description: 'An array of objects with the following types: SECTION, FACT, BOARD'
          items:
            $ref: '#/components/schemas/BoardItem'
          type: array
        title:
          description: The title of the directory
          type: string
      type: object
    CardInfo:
      properties:
        boards:
          items:
            $ref: '#/components/schemas/Board'
          type: array
        analytics:
          additionalProperties:
            format: int64
            type: integer
          type: object
        membersWithCardView:
          format: int64
          type: integer
        membersWithoutCardView:
          format: int64
          type: integer
      type: object
    UserGroup:
      properties:
        name:
          description: Group Name
          type: string
        id:
          description: ID of the group
          type: string
        members:
          items:
            $ref: '#/components/schemas/UserGroupMember'
          type: array
        dateCreated:
          description: 'Date the group was created. Dates are in ISO-8601 format. Example date (January 2nd 2014 12pm UTC): 2014-01-02T12:00:00.000+0000'
          format: date-time
          type: string
        expertIdRank:
          format: int64
          type: integer
        numberOfCardsAsVerifier:
          format: int32
          type: integer
        managedByScim:
          type: boolean
        groupIdentifier:
          type: string
        numberOfMembers:
          format: int32
          type: integer
        modifiable:
          type: boolean
        userModifiable:
          type: boolean
        singleUser:
          type: boolean
        role:
          enum:
          - ADMIN
          - AUTHOR
          - MEMBER
          - COLL_ADMIN
          type: string
      type: object
    BoardItem:
      discriminator:
        propertyName: type
        mappings:
          fact: '#/components/schemas/BoardFact'
          section: '#/components/schemas/BoardSection'
          board: '#/components/schemas/SubBoard'
      properties:
        itemId:
          type: string
        type:
          enum:
          - section
          - fact
          - board
          type: string
      required:
      - type
      type: object
    User:
      properties:
        id:
          description: The identifier of this User
          type: string
        userProfile:
          $ref: '#/components/schemas/UserProfile'
        lastName:
          description: The user's last name
          type: string
        firstName:
          description: The user's first name
          type: string
        profilePicUrl:
          description: The profile picture url for the user
          type: string
        joinedDate:
          format: date-time
          type: string
        status:
          description: The status of a User can be ACTIVE or PENDING. The User must verify their email address to be considered ACTIVE.
          enum:
          - ACTIVE
          - PENDING
          type: string
        email:
          description: The user's email address
          type: string
      required:
      - email
      - firstName
      - lastName
      type: object
    UserProfile:
      description: Specifies additional information about a Guru User
      properties:
        roleLevel:
          description: The level at which the user operates in their current role
          type: string
        useCaseList:
          description: Describes different ways the user intends to use Guru
          items:
            $ref: '#/components/schemas/UseCase'
          type: array
        role:
          description: The functional role a Guru user performs on their team
          type: string
      type: object
    Tag:
      description: Information about the Tag and its Category
      properties:
        value:
          description: The name of the Tag
          type: string
        id:
          description: The ID of the Tag
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        numberOfCards:
          description: The number of cards associated with this Tag
          format: int64
          type: integer
        categoryId:
          description: If the tag belongs to a category, this is the ID for the category
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        categoryName:
          description: If the tag belongs to a category, this is the name for the category
          type: string
      type: object
    UserGroupMember:
      properties:
        id:
          description: ID of the group member
          type: string
        dateCreated:
          description: 'Date the group member was added to the group. Dates are in ISO-8601 format. Example date (January 2nd 2014 12pm UTC): 2014-01-02T12:00:00.000+0000'
          format: date-time
          type: string
        managedByScim:
          type: boolean
        user:
          $ref: '#/components/schemas/User'
      required:
      - user
      type: object
    CardAttachment:
      description: Information about attachments within a Card.
      properties:
        id:
          description: The ID of the CardAttachment
          example: 'IDs are formatted like this: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
          type: string
        size:
          description: The attached file's size in bytes
          example: 1000
          format: int64
          type: integer
        extension:
          description: The attached file's extension
          example: csv
          type: string
        link:
          description: Link to where the uploaded file is hosted in Guru's servers
          type: string
        thumbnailLink:
          description: Link to where the thumbnail for the uploaded file is hosted in Guru's servers
          type: string
        previewable:
          type: boolean
        mimetype:
          type: string
        filename:
          description: The file name and extension
          example: file-name.png
          type: string
      type: object
    ImageCropSpec:
      properties:
        x:
          format: int32
          type: integer
        y:
          format: int32
          type: integer
        width:
          format: int32
          type: integer
        height:
          format: int32
          type: integer
      type: object
    UseCase:
      properties:
        description:
          description: A description of this use case
          type: string
      type: object
    Stats:
      discriminator:
        propertyName: type
        mappings:
          card-count: '#/components/schemas/CollectionCardCount'
          collection-trust-score: '#/components/schemas/CollectionTrustScore'
          team-card-count: '#/components/schemas/TeamCardCount'
          team-trust-score: '#/components/schemas/TeamTrustScore'
      properties:
        type:
          enum:
          - team-card-count
          - team-trust-score
          - collection-trust-score
          - card-count
          type: string
      required:
      - type
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token.
x-refined-from:
- guru-openapi.json
- guru-openapi.yml
x-original-swagger-version: '2.0'