openapi: 3.0.0
info:
  title: Fieldguide api sheet-rows API
  description: An API for interacting with the [Fieldguide](https://fieldguide.io) platform
  version: v1
  contact: {}
servers:
- url: https://api.fieldguide.io
  description: Fieldguide API
security:
- bearer: []
tags:
- name: sheet-rows
  description: Endpoints used to interact with Fieldguide Sheet Rows
paths:
  /v1/sheet-rows/{uuid}/requests:
    get:
      operationId: list_requests_by_sheet_row_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Sheet Row to retrieve requests for
        schema:
          format: uuid
          type: string
      - name: page
        required: false
        in: query
        schema:
          type: number
          default: 1
          nullable: true
      - name: per_page
        required: false
        in: query
        schema:
          type: number
          default: 50
          nullable: true
          minimum: 1
          maximum: 200
      - name: sort_order
        required: false
        in: query
        description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: The Requests for the Sheet Row
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/RequestRead'
                - properties:
                    _links:
                      type: object
                      required:
                      - self
                      - first
                      - last
                      properties:
                        self:
                          type: object
                          description: The URL for the current page being fetched
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=2&per_page=50
                        first:
                          type: object
                          description: The URL for the first page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        last:
                          type: object
                          description: The URL for the last page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=10&per_page=50
                        previous:
                          type: object
                          description: The URL for the previous page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        next:
                          type: object
                          description: The URL for the next page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=3&per_page=50
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `requests:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: List Requests that belong to the specified Sheet Row
      tags:
      - sheet-rows
      x-required-scopes:
      - requests:read
  /v1/requests/{uuid}/sheet-rows:
    get:
      operationId: list_sheet_rows_by_request_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Request for which to get Sheet Rows
        schema:
          format: uuid
          type: string
      - name: page
        required: false
        in: query
        schema:
          type: number
          default: 1
          nullable: true
      - name: per_page
        required: false
        in: query
        schema:
          type: number
          default: 50
          nullable: true
          minimum: 1
          maximum: 200
      - name: sort_order
        required: false
        in: query
        description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: The Sheet Rows to which the Request is linked
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/SheetRowRead'
                - properties:
                    _links:
                      type: object
                      required:
                      - self
                      - first
                      - last
                      properties:
                        self:
                          type: object
                          description: The URL for the current page being fetched
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=2&per_page=50
                        first:
                          type: object
                          description: The URL for the first page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        last:
                          type: object
                          description: The URL for the last page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=10&per_page=50
                        previous:
                          type: object
                          description: The URL for the previous page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        next:
                          type: object
                          description: The URL for the next page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=3&per_page=50
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `sheets:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: List Sheet Rows that belong to the specified Request
      tags:
      - sheet-rows
      x-required-scopes:
      - sheets:read
  /v1/sheets/{uuid}/sheet-rows:
    get:
      operationId: list_sheet_rows_by_sheet_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Sheet for which to get Sheet Rows
        schema:
          format: uuid
          type: string
      - name: page
        required: false
        in: query
        schema:
          type: number
          default: 1
          nullable: true
      - name: per_page
        required: false
        in: query
        schema:
          type: number
          default: 50
          nullable: true
          minimum: 1
          maximum: 200
      - name: sort_order
        required: false
        in: query
        description: Sort order for paginated results. Use `desc` to reverse the default ascending order.
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: The Sheet Rows to which the Sheet is linked
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/SheetRowRead'
                - properties:
                    _links:
                      type: object
                      required:
                      - self
                      - first
                      - last
                      properties:
                        self:
                          type: object
                          description: The URL for the current page being fetched
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=2&per_page=50
                        first:
                          type: object
                          description: The URL for the first page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        last:
                          type: object
                          description: The URL for the last page of the set
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=10&per_page=50
                        previous:
                          type: object
                          description: The URL for the previous page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=1&per_page=50
                        next:
                          type: object
                          description: The URL for the next page in the set, if there is one
                          properties:
                            href:
                              type: string
                              example: https://api.fieldguide.io/v1/example?page=3&per_page=50
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `sheets:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: List Sheet Rows that belong to the specified Sheet
      tags:
      - sheet-rows
      x-required-scopes:
      - sheets:read
  /v1/sheet-rows/{uuid}/cells:
    get:
      operationId: list_sheet_row_cells_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Sheet Row for which to get cell values
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The cells of the Sheet Row
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SheetRowCellRead'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `sheets:read`)
        '404':
          description: Resource not found
        '422':
          description: Unprocessable Entity (the Sheet Row contains more than 1000 columns)
        '429':
          description: Too many requests
      summary: Get the cells of a Sheet Row
      tags:
      - sheet-rows
      x-required-scopes:
      - sheets:read
    patch:
      operationId: update_sheet_row_cells_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Sheet Row for which to update cell values
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SheetRowCellUpdate'
      responses:
        '204':
          description: No content. The updates were made successfully.
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `sheets:write`)
        '404':
          description: Resource not found
        '422':
          description: Unprocessable Entity
        '429':
          description: Too many requests
      summary: Updates the cells of a Sheet Row
      tags:
      - sheet-rows
      x-required-scopes:
      - sheets:write
components:
  schemas:
    SheetRowCellRead:
      type: object
      properties:
        column_uuid:
          type: string
          format: uuid
          example: 4d50d252-be0c-4d69-b77a-5bbdfef83f54
        value:
          oneOf:
          - type: string
            nullable: true
          - type: number
            nullable: true
      required:
      - column_uuid
      - value
    HalLink:
      type: object
      properties:
        href:
          type: string
          example: https://example.com/resource/or/path
          format: uri
        title:
          type: string
          description: A human-readable title for the link
          example: A description for the link
        type:
          type: string
          description: The content-type
          example: text/html
      required:
      - href
      - type
    SheetRowRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 4d50d252-be0c-4d69-b77a-5bbdfef83f54
        keys:
          type: array
          items:
            type: string
            example: 1.1.1
        _links:
          $ref: '#/components/schemas/SheetReadLinks'
      required:
      - uuid
      - keys
      - _links
    SheetReadLinks:
      type: object
      properties:
        fieldguide:
          description: A URL the user can visit to view the Sheet within the Fieldguide web application
          example:
            href: https://app.fieldguide.io/engagements/82027/workplan/3
            title: View the Sheet in Fieldguide
            type: text/html
          allOf:
          - $ref: '#/components/schemas/HalLink'
      required:
      - fieldguide
    RequestStatus:
      type: string
      enum:
      - Open
      - Update Requested
      - Complete
      - Ready For Review
      - Draft
      description: The request's current status in the evidence-collection workflow.
    RequestReadLinks:
      type: object
      properties:
        fieldguide:
          description: A URL the user can visit to view the Request within the Fieldguide web application
          example:
            href: https://app.fieldguide.io/inbox?open=true&id=47923
            title: View this Request in Fieldguide
            type: text/html
          allOf:
          - $ref: '#/components/schemas/HalLink'
      required:
      - fieldguide
    SheetRowCellUpdate:
      type: object
      properties:
        column_uuid:
          type: string
          format: uuid
          example: 4d50d252-be0c-4d69-b77a-5bbdfef83f54
        value:
          oneOf:
          - type: string
            nullable: true
          - type: number
            nullable: true
      required:
      - column_uuid
      - value
    RequestRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 4d50d252-be0c-4d69-b77a-5bbdfef83f54
        title:
          type: string
          example: Employees hired in 2023
        description:
          type: string
          example: Please provide a list of employees hired this calendar year along with full HR profiles
        status:
          description: The request's current status in the evidence-collection workflow.
          allOf:
          - $ref: '#/components/schemas/RequestStatus'
        identifier:
          type: string
          description: An external identifier that can be used by integrated systems
          example: REQ-1234
        client_company_uuid:
          type: string
          format: uuid
          example: 60d593b6-1c59-4f30-bf9c-56901af906a7
        status_label:
          type: string
          example: Waiting for Specification
          description: If the status is "Draft", this can be a custom label. Otherwise, it will be the same value as the "status" property.
        created_at:
          format: date-time
          type: string
          example: '2023-01-01T12:30:00.000Z'
        due_date:
          type: string
          format: date
          example: '2024-05-01'
          nullable: true
        client_owner_user_uuids:
          type: array
          items:
            type: string
            format: uuid
            example: edbf4962-20eb-499e-a7fa-eaff50c81630
        tags:
          type: array
          items:
            type: string
            example: tag-name
        engagement_uuids:
          type: array
          items:
            type: string
            format: uuid
            example: d51b4959-a6b0-4b8a-a251-8b5f7be7765e
        _links:
          $ref: '#/components/schemas/RequestReadLinks'
      required:
      - uuid
      - title
      - description
      - status
      - identifier
      - client_company_uuid
      - status_label
      - created_at
      - due_date
      - client_owner_user_uuids
      - tags
      - engagement_uuids
      - _links
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
externalDocs:
  description: Fieldguide API Documentation
  url: https://fieldguide.io/developers