openapi: 3.0.3
info:
  title: Reflektive API
  description: >-
    The Reflektive REST API provides programmatic access to performance
    management data including real-time feedback, performance reviews, goal
    management, engagement surveys, and asynchronous report generation.
    Authentication uses a company-level token passed as an HTTP Authorization
    header. The API is versioned (v1 and v2), with v2 supporting multi-recipient
    team recognition in addition to the core v1 resource set.
  version: "2.0"
  contact:
    email: support@reflektive.com
  x-api-id: reflektive:reflektive-api
  x-audience: external-public
servers:
  - url: https://api.reflektive.com
    description: Reflektive Production API

security:
  - tokenAuth: []

tags:
  - name: Real-time Feedback (v1)
    description: V1 endpoint for real-time peer feedback between a single sender and recipient.
  - name: Real-time Feedback (v2)
    description: >-
      V2 endpoint for real-time feedback with support for Team Recognition
      (multiple recipients).
  - name: Tasks
    description: >-
      Asynchronous task objects used to track the status of report generation
      jobs.
  - name: Reports
    description: >-
      Report generation endpoints that kick off asynchronous jobs and return a
      task UUID for status polling.

paths:
  /v1/real-time-feedback:
    get:
      operationId: listV1RealTimeFeedback
      summary: List real-time feedback (v1)
      description: >-
        Returns a paginated list of all public, positive real-time feedback
        records. By default 200 results are returned per query. When more than
        200 results exist, the response includes pagination links for the next
        and last pages.
      tags:
        - Real-time Feedback (v1)
      parameters:
        - name: created_before
          in: query
          description: >-
            A UNIX timestamp representing the oldest time a feedback was
            created. Defaults to the time the request was issued.
          required: false
          schema:
            type: integer
            format: int64
            example: 1477877614
        - name: created_after
          in: query
          description: >-
            A UNIX timestamp representing the most recent time a feedback was
            created. Defaults to 1 day prior to the time the request was
            issued.
          required: false
          schema:
            type: integer
            format: int64
            example: 1477877614
        - name: page
          in: query
          description: >-
            An offset for the feedback results. The endpoint returns 200
            results per query.
          required: false
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        "200":
          description: Paginated list of real-time feedback records.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1FeedbackListResponse"
              example:
                links:
                  self: /v1/real-time-feedback?created_after=1477877614
                  next: /v1/real-time-feedback?created_after=1477877614?page=2
                  last: /v1/real-time-feedback?created_after=1477877614?page=5
                data:
                  - uuid: e8678ff9-3ae4-4b2b-b7af-f7240155f753
                    sender:
                      uuid: 04b09952-6b79-454e-8306-9c7f015267b5
                      email: darth.vader@example.com
                      name: Darth Vader
                      photo: https://www.example.com/darth.vader.jpg
                    recipient:
                      uuid: addd9666-788a-4eb6-82a2-225a7600e4c9
                      email: luke.skywalker@example.com
                      name: Luke Skywalker
                      photo: https://www.example.com/luke.skywalker.jpg
                    content: Most impressive.
                    created_at: "2016-10-31T23:43:20Z"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/task/{uuid}:
    get:
      operationId: getTask
      summary: Show task status
      description: >-
        Returns the current status of a given asynchronous task. Tasks are used
        to monitor the status of report generation jobs. When a report
        generation completes, the task status updates to "completed" and the
        metadata field contains a temporary download link (expires after 15
        minutes by default).
      tags:
        - Tasks
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the task to retrieve.
          schema:
            type: string
            format: uuid
            example: c4ff9ae5-558d-400c-a768-ad132a3e4c6c
      responses:
        "200":
          description: Task object with current status and metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TaskResponse"
              examples:
                pending:
                  summary: Task pending
                  value:
                    data:
                      uuid: c4ff9ae5-558d-400c-a768-ad132a3e4c6c
                      status: pending
                      metadata: {}
                completed:
                  summary: Task completed with download link
                  value:
                    data:
                      uuid: c4ff9ae5-558d-400c-a768-ad132a3e4c6c
                      status: completed
                      metadata:
                        link: http://www.some_download_link.com
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /v1/reports/reviews:
    post:
      operationId: generateReviewsReport
      summary: Generate a calibrations report
      description: >-
        Kicks off an asynchronous report generation job and returns the UUID of
        a Task object that can be polled for completion. When the report is
        ready, the task metadata will contain a temporary download link.
      tags:
        - Reports
      parameters:
        - name: report_type
          in: query
          required: true
          description: The type of report to generate.
          schema:
            type: string
            enum:
              - calibrations
            example: calibrations
        - name: cycle_uuid
          in: query
          required: true
          description: The UUID of the review cycle to generate the report for.
          schema:
            type: string
            format: uuid
            example: eadf6d0c-00e3-45ce-8332-1673226f0321
      responses:
        "200":
          description: >-
            Report generation job accepted. Returns the task UUID to poll for
            completion.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReportTaskResponse"
              example:
                data:
                  task_uuid: 194b434f-ebbb-4aae-a975-34681d13c1b3
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /v2/real-time-feedback:
    get:
      operationId: listV2RealTimeFeedback
      summary: List real-time feedback (v2)
      description: >-
        Returns a paginated list of all public, positive real-time feedback
        records using the v2 schema. The v2 endpoint adds support for Team
        Recognition — feedback sent to multiple recipients simultaneously.
        By default 200 results are returned per query.
      tags:
        - Real-time Feedback (v2)
      parameters:
        - name: created_before
          in: query
          description: >-
            A UNIX timestamp representing the oldest time a feedback was
            created. Defaults to the time the request was issued.
          required: false
          schema:
            type: integer
            format: int64
            example: 1477877614
        - name: created_after
          in: query
          description: >-
            A UNIX timestamp representing the most recent time a feedback was
            created. Defaults to 1 day prior to the time the request was
            issued.
          required: false
          schema:
            type: integer
            format: int64
            example: 1477877614
        - name: page
          in: query
          description: >-
            An offset for the feedback results. The endpoint returns 200
            results per query.
          required: false
          schema:
            type: integer
            default: 1
            example: 1
      responses:
        "200":
          description: Paginated list of real-time feedback records (v2, multi-recipient).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V2FeedbackListResponse"
              example:
                links:
                  self: /v2/real-time-feedback?created_after=1477877614
                  next: /v2/real-time-feedback?created_after=1477877614?page=2
                  last: /v2/real-time-feedback?created_after=1477877614?page=5
                data:
                  - uuid: e8678ff9-3ae4-4b2b-b7af-f7240155f753
                    sender:
                      uuid: 04b09952-6b79-454e-8306-9c7f015267b5
                      email: darth.vader@example.com
                      name: Darth Vader
                      photo: https://www.example.com/darth.vader.jpg
                    recipients:
                      - uuid: addd9666-788a-4eb6-82a2-225a7600e4c9
                        email: luke.skywalker@example.com
                        name: Luke Skywalker
                        photo: https://www.example.com/luke.skywalker.jpg
                    content: Most impressive.
                    created_at: "2016-10-31T23:43:20Z"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Token-based authentication. Pass the header as:
        `Authorization: Token token=<your_api_key>`. Contact
        support@reflektive.com to obtain an API key.

  schemas:
    Employee:
      type: object
      description: >-
        Represents a user working for a Reflektive company.
      properties:
        uuid:
          type: string
          format: uuid
          description: A unique identifier associated with this employee.
          example: 04b09952-6b79-454e-8306-9c7f015267b5
        email:
          type: string
          format: email
          description: The email address of the employee.
          example: darth.vader@example.com
        name:
          type: string
          description: The employee's full name.
          example: Darth Vader
        photo:
          type: string
          format: uri
          nullable: true
          description: A URL pointing to a photograph of the employee, if available.
          example: https://www.example.com/darth.vader.jpg
      required:
        - uuid
        - email
        - name

    V1Feedback:
      type: object
      description: >-
        A real-time feedback record (v1) with a single sender and single
        recipient.
      properties:
        uuid:
          type: string
          format: uuid
          description: A unique identifier associated with this feedback.
          example: e8678ff9-3ae4-4b2b-b7af-f7240155f753
        sender:
          $ref: "#/components/schemas/Employee"
        recipient:
          $ref: "#/components/schemas/Employee"
        content:
          type: string
          description: The publicly visible content of the feedback.
          example: Most impressive.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the feedback was created and sent.
          example: "2016-10-31T23:43:20Z"
      required:
        - uuid
        - sender
        - recipient
        - content
        - created_at

    V2Feedback:
      type: object
      description: >-
        A real-time feedback record (v2) supporting Team Recognition — one
        sender and one or more recipients.
      properties:
        uuid:
          type: string
          format: uuid
          description: A unique identifier associated with this feedback.
          example: e8678ff9-3ae4-4b2b-b7af-f7240155f753
        sender:
          $ref: "#/components/schemas/Employee"
        recipients:
          type: array
          description: >-
            An array of Employee objects representing all people who received
            this feedback (supports Team Recognition).
          items:
            $ref: "#/components/schemas/Employee"
          minItems: 1
        content:
          type: string
          description: The publicly visible content of the feedback.
          example: Most impressive.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the feedback was created and sent.
          example: "2016-10-31T23:43:20Z"
      required:
        - uuid
        - sender
        - recipients
        - content
        - created_at

    PaginationLinks:
      type: object
      description: Pagination links included when results span multiple pages.
      properties:
        self:
          type: string
          description: The URL of the current result set.
          example: /v1/real-time-feedback?created_after=1477877614
        next:
          type: string
          description: The URL of the next page of results.
          example: /v1/real-time-feedback?created_after=1477877614?page=2
        last:
          type: string
          description: The URL of the last page of results.
          example: /v1/real-time-feedback?created_after=1477877614?page=5
      required:
        - self

    V1FeedbackListResponse:
      type: object
      properties:
        links:
          $ref: "#/components/schemas/PaginationLinks"
        data:
          type: array
          items:
            $ref: "#/components/schemas/V1Feedback"
      required:
        - links
        - data

    V2FeedbackListResponse:
      type: object
      properties:
        links:
          $ref: "#/components/schemas/PaginationLinks"
        data:
          type: array
          items:
            $ref: "#/components/schemas/V2Feedback"
      required:
        - links
        - data

    Task:
      type: object
      description: >-
        Tracks the status of an asynchronous job such as report generation.
      properties:
        uuid:
          type: string
          format: uuid
          description: A unique identifier for this task.
          example: c4ff9ae5-558d-400c-a768-ad132a3e4c6c
        status:
          type: string
          description: >-
            The current status of the task. One of "pending", "failed", or
            "completed".
          enum:
            - pending
            - failed
            - completed
          example: pending
        metadata:
          type: object
          description: >-
            A JSON object containing metadata about the task. For completed
            report tasks this includes a "link" property with a temporary
            download URL (expires after 15 minutes by default).
          additionalProperties: true
          example:
            link: http://www.some_download_link.com
      required:
        - uuid
        - status
        - metadata

    TaskResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Task"
      required:
        - data

    ReportTaskResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            task_uuid:
              type: string
              format: uuid
              description: >-
                The UUID of the Task created for this report generation job.
                Use GET /v1/task/{uuid} to poll for completion.
              example: 194b434f-ebbb-4aae-a975-34681d13c1b3
          required:
            - task_uuid
      required:
        - data

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.

  responses:
    Unauthorized:
      description: Could not authenticate using the provided API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: You do not have permission to view the requested resource.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource could not be found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"