openapi: 3.0.1
info:
  title: News Rest APIs
  description: News addon used Rest endpoints
  license:
    name: AGPL
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: "1.0"
tags:
- name: v1/news
  description: Managing news
- name: v1/news/targeting
  description: Manage news targeting operations
paths:
  /v1/news:
    get:
      tags:
      - v1/news
      summary: Get news list
      description: "This gets the list of news with the given search text, of the\
        \ given author, in the given space or spaces, with the given publication state,\
        \ with the given pinned state if the authenticated user is a member of the\
        \ spaces or a super manager."
      operationId: getNews
      parameters:
      - name: author
        in: query
        description: News author
        required: true
        schema:
          type: string
      - name: spaces
        in: query
        description: News spaces
        required: true
        schema:
          type: string
      - name: filter
        in: query
        description: News filter
        required: true
        schema:
          type: string
      - name: text
        in: query
        description: search text
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: News pagination offset
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: News pagination limit
        schema:
          type: integer
          format: int32
          default: 10
      - name: returnSize
        in: query
        description: News total size
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: News list returned
        "401":
          description: User not authorized to get the news list
        "404":
          description: News list not found
        "500":
          description: Internal server error
    post:
      tags:
      - v1/news
      summary: Create a news
      description: "This creates the news if the authenticated user is a member of\
        \ the space or a spaces super manager. The news is created in draft status,\
        \ unless the publicationState property is set to 'published'."
      operationId: createNews
      requestBody:
        description: News object to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/News'
        required: true
      responses:
        "200":
          description: News created
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to create the news
        "500":
          description: Internal server error
  /v1/news/attachments/{attachmentId}:
    get:
      tags:
      - v1/news
      summary: Get a news attachment
      description: This gets the news attachment with the given id if the authenticated
        user is a member of the space or a spaces super manager.
      operationId: getNewsAttachmentById
      parameters:
      - name: attachmentId
        in: path
        description: News attachment id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/attachments/{attachmentId}/file:
    get:
      tags:
      - v1/news
      summary: Download a news attachment
      description: This downloads the news attachment with the given id if the authenticated
        user is a member of the space or a spaces super manager.
      operationId: getNewsAttachmentBinaryById
      parameters:
      - name: attachmentId
        in: path
        description: News attachment id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/attachments/{attachmentId}/open:
    get:
      tags:
      - v1/news
      summary: Opens a news attachment
      description: This opens the news attachment with the given id if the authenticated
        user is a member of the space or a spaces super manager.
      operationId: openNewsAttachmentById
      parameters:
      - name: attachmentId
        in: path
        description: News attachment id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/byActivity/{activityId}:
    get:
      tags:
      - v1/news
      summary: Get a news identified by its activity or shared activity identifier
      description: This gets the news with the given id if the authenticated user
        is a member of the space or a spaces super manager.
      operationId: getNewsByActivityId
      parameters:
      - name: activityId
        in: path
        description: Activity id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/byTarget/{targetName}:
    get:
      tags:
      - v1/news
      summary: Get news list
      description: This gets the list of news by the given target.
      operationId: getNewsByTarget
      parameters:
      - name: targetName
        in: path
        description: News target name
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: News pagination offset
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: News pagination limit
        schema:
          type: integer
          format: int32
          default: 10
      - name: returnSize
        in: query
        description: News total size
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: News list returned
        "401":
          description: User not authorized to get the news list
        "404":
          description: News list not found
        "500":
          description: Internal server error
  /v1/news/canCreateNews/{spaceId}:
    get:
      tags:
      - v1/news
      summary: check if the current user can create a news in the given space
      description: This checks if the current user can create a news in the given
        space
      operationId: canCreateNews
      parameters:
      - name: spaceId
        in: path
        description: space id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User ability to create a news is returned
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to create a news
        "404":
          description: Space not found
        "500":
          description: Internal server error
  /v1/news/canPublishNews:
    get:
      tags:
      - v1/news
      summary: check if the current user can publish a news to all users
      description: This checks if the current user can publish a news to all users
      operationId: canPublishNews
      parameters:
      - name: spaceId
        in: query
        description: space id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User ability to publish a news is returned
        "401":
          description: User not authorized to publish a news
  /v1/news/canScheduleNews/{spaceId}:
    get:
      tags:
      - v1/news
      summary: check if the current user can schedule a news in the given space
      description: This checks if the current user can schedule a news in the given
        space
      operationId: canScheduleNews
      parameters:
      - name: spaceId
        in: path
        description: space id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User ability to schedule a news
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to schedule a news
        "404":
          description: Space not found
        "500":
          description: Internal server error
  /v1/news/markAsRead/{id}:
    post:
      tags:
      - v1/news
      summary: mark a news article as read
      description: This marks a news article as read by the user who accessed its
        details.
      operationId: markNewsAsRead
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Request fulfilled
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/schedule:
    patch:
      tags:
      - v1/news
      summary: Schedule a news
      description: "This schedules the news if the authenticated user is a member\
        \ of the space or a spaces super manager. The news is created in staged status,\
        \ after reaching a date of publication startPublishedDate, the publicationState\
        \ property is set to 'published'."
      operationId: scheduleNews
      requestBody:
        description: News object to be scheduled
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/News'
        required: true
      responses:
        "200":
          description: News scheduled
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to schedule the news
        "500":
          description: Internal server error
  /v1/news/search:
    get:
      tags:
      - v1/news
      summary: Search the list of news available with query
      description: Search the list of news available with query
      operationId: search
      parameters:
      - name: query
        in: query
        description: Term to search
        required: true
        schema:
          type: string
      - name: expand
        in: query
        description: Properties to expand
        schema:
          type: string
      - name: offset
        in: query
        description: Offset
        schema:
          type: integer
          format: int32
          default: 0
      - name: tags
        in: query
        description: Tag names used to search news
        required: true
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: Limit
        schema:
          type: integer
          format: int32
          default: 20
      - name: favorites
        in: query
        description: Favorites
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: Request fulfilled
        "400":
          description: Invalid query input
        "500":
          description: Internal server error
  /v1/news/targeting:
    get:
      tags:
      - v1/news/targeting
      summary: Get all news targets
      description: Get all news targets
      operationId: getAllTargets
      responses:
        "200":
          description: Request fulfilled
        "500":
          description: Internal server error
    post:
      tags:
      - v1/news/targeting
      summary: Create news target
      description: Create news target
      operationId: createNewsTarget
      requestBody:
        description: News target to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsTargetingEntity'
        required: true
      responses:
        "401":
          description: User not authorized to create news target
        "403":
          description: Forbidden operation
        "409":
          description: Conflict operation
        "500":
          description: Internal server error
  /v1/news/targeting/allowed:
    get:
      tags:
      - v1/news/targeting
      summary: Get all allowed news targets of the current user
      description: Get all allowed news targets of the current user
      operationId: getAllowedTargets
      responses:
        "200":
          description: Request fulfilled
        "500":
          description: Internal server error
  /v1/news/targeting/{originalTargetName}:
    put:
      tags:
      - v1/news/targeting
      summary: Update an existing news target
      description: Update an existing news target
      operationId: updateNewsTarget
      parameters:
      - name: originalTargetName
        in: path
        description: Original news target name
        required: true
        schema:
          type: string
      requestBody:
        description: News target to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewsTargetingEntity'
        required: true
      responses:
        "401":
          description: Unauthorized operation
        "403":
          description: Forbidden operation
        "404":
          description: Object not found
        "409":
          description: Conflict operation
        "500":
          description: Internal server error
  /v1/news/targeting/{targetName}:
    delete:
      tags:
      - v1/news/targeting
      summary: Delete news target
      description: This deletes news target
      operationId: deleteTarget
      parameters:
      - name: targetName
        in: path
        description: Target name
        required: true
        schema:
          type: string
      - name: delay
        in: query
        description: Time to effectively delete news target
        schema:
          type: integer
          format: int64
      responses:
        "200":
          description: News target deleted
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to delete the news target
        "500":
          description: Internal server error
  /v1/news/targeting/{targetName}/undoDelete:
    post:
      tags:
      - v1/news/targeting
      summary: Undo deleting news target if not yet effectively deleted
      description: Undo deleting news target if not yet effectively deleted
      operationId: undoDeleteTarget
      parameters:
      - name: targetName
        in: path
        description: News target name identifier
        required: true
        schema:
          type: string
      responses:
        "400":
          description: Invalid query input
        "403":
          description: Forbidden operation
  /v1/news/{id}:
    get:
      tags:
      - v1/news
      summary: Get a news
      description: This gets the news with the given id if the authenticated user
        is a member of the space or a spaces super manager.
      operationId: getNewsById
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: fields
        required: true
        schema:
          type: string
      - name: editMode
        in: query
        description: Is edit mode
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
    put:
      tags:
      - v1/news
      summary: Create a news
      description: This updates the news if the authenticated user is a member of
        the space or a spaces super manager.
      operationId: updateNews
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      - name: post
        in: query
        description: Post news
        schema:
          type: boolean
      requestBody:
        description: News object to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/News'
        required: true
      responses:
        "200":
          description: News updated
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to update the news
        "500":
          description: Internal server error
    delete:
      tags:
      - v1/news
      summary: Delete news
      description: This deletes the news
      operationId: deleteNews
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      - name: isDraft
        in: query
        description: Is draft to delete
        schema:
          type: boolean
          default: false
      - name: delay
        in: query
        description: Time to effectively delete news
        schema:
          type: integer
          format: int64
      responses:
        "200":
          description: News deleted
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to delete the news
        "500":
          description: Internal server error
    patch:
      tags:
      - v1/news
      summary: Update a news
      description: This updates the sent fields of a news
      operationId: patchNews
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      requestBody:
        description: News object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/News'
        required: true
      responses:
        "200":
          description: News updated
        "400":
          description: Invalid query input
        "401":
          description: User not authorized to update the news
        "500":
          description: Internal server error
  /v1/news/{id}/click:
    post:
      tags:
      - v1/news
      summary: Log a click action on a news
      description: This logs a message when the user performs a click on a news
      operationId: clickOnNews
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      requestBody:
        description: The clicked element
        content:
          '*/*':
            schema:
              type: string
        required: true
      responses:
        "200":
          description: Click logged
        "400":
          description: Invalid query input
        "500":
          description: Internal server error
  /v1/news/{id}/illustration:
    get:
      tags:
      - v1/news
      summary: Get a news illustration
      description: This gets the news illustration with the given id if the authenticated
        user is a member of the space or a spaces super manager.
      operationId: getNewsIllustration
      parameters:
      - name: id
        in: path
        description: News id
        required: true
        schema:
          type: string
      - name: v
        in: query
        description: last modified date
        schema:
          type: integer
          format: int64
      - name: size
        in: query
        description: resized image size
        schema:
          type: string
      responses:
        "200":
          description: News returned
        "401":
          description: User not authorized to get the news
        "404":
          description: News not found
        "500":
          description: Internal server error
  /v1/news/{id}/undoDelete:
    post:
      tags:
      - v1/news
      summary: Undo deleting news if not yet effectively deleted
      description: Undo deleting news if not yet effectively deleted
      operationId: undoDeleteNews
      parameters:
      - name: id
        in: path
        description: News node identifier
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Request fulfilled
        "400":
          description: Invalid query input
        "403":
          description: Forbidden operation
        "401":
          description: Unauthorized operation
        "500":
          description: Internal server error
components:
  schemas:
    Metadata:
      type: object
      properties:
        audienceId:
          type: integer
          format: int64
        createdDate:
          type: integer
          format: int64
        creatorId:
          type: integer
          format: int64
        id:
          type: integer
          format: int64
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        type:
          $ref: '#/components/schemas/MetadataType'
        typeName:
          type: string
    MetadataItem:
      type: object
      properties:
        createdDate:
          type: integer
          format: int64
        creatorId:
          type: integer
          format: int64
        id:
          type: integer
          format: int64
        metadata:
          $ref: '#/components/schemas/Metadata'
        metadataTypeName:
          type: string
        object:
          $ref: '#/components/schemas/MetadataObject'
        objectId:
          type: string
        objectType:
          type: string
        parentObjectId:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string
        spaceId:
          type: integer
          format: int64
    MetadataObject:
      type: object
      properties:
        id:
          type: string
        parentId:
          type: string
        spaceId:
          type: integer
          format: int64
        type:
          type: string
    MetadataType:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    News:
      type: object
      properties:
        activities:
          type: string
        activityId:
          type: string
        activityPosted:
          type: boolean
        archived:
          type: boolean
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/NewsAttachment'
        audience:
          type: string
        author:
          type: string
        authorAvatarUrl:
          type: string
        authorDisplayName:
          type: string
        body:
          type: string
        canArchive:
          type: boolean
        canDelete:
          type: boolean
        canEdit:
          type: boolean
        canPublish:
          type: boolean
        commentsCount:
          type: integer
          format: int32
        creationDate:
          type: string
          format: date-time
        draftUpdateDate:
          type: string
          format: date-time
        draftUpdater:
          type: string
        draftUpdaterDisplayName:
          type: string
        draftUpdaterUserName:
          type: string
        draftVisible:
          type: boolean
        hiddenSpace:
          type: boolean
        id:
          type: string
        illustration:
          type: array
          items:
            type: string
            format: byte
        illustrationMimeType:
          type: string
        illustrationURL:
          type: string
        illustrationUpdateDate:
          type: string
          format: date-time
        likesCount:
          type: integer
          format: int32
        metadatas:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/MetadataItem'
        originalBody:
          type: string
        path:
          type: string
        publicationDate:
          type: string
          format: date-time
        publicationState:
          type: string
        publishDate:
          type: string
          format: date-time
        published:
          type: boolean
        schedulePostDate:
          type: string
        sharedInSpacesList:
          type: array
          items:
            type: string
        spaceAvatarUrl:
          type: string
        spaceDisplayName:
          type: string
        spaceId:
          type: string
        spaceMember:
          type: boolean
        spaceUrl:
          type: string
        summary:
          type: string
        targets:
          type: array
          items:
            type: string
        timeZoneId:
          type: string
        title:
          type: string
        updateDate:
          type: string
          format: date-time
        updater:
          type: string
        updaterFullName:
          type: string
        uploadId:
          type: string
        url:
          type: string
        viewsCount:
          type: integer
          format: int64
    NewsAttachment:
      type: object
      properties:
        id:
          type: string
        mimetype:
          type: string
        name:
          type: string
        size:
          type: integer
          format: int32
        uploadId:
          type: string
    NewsTargetingEntity:
      type: object
      properties:
        name:
          type: string
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/NewsTargetingPermissionsEntity'
        properties:
          type: object
          additionalProperties:
            type: string
    NewsTargetingPermissionsEntity:
      type: object
      properties:
        avatar:
          type: string
        id:
          type: string
        name:
          type: string
        providerId:
          type: string
        remoteId:
          type: string