openapi: 3.0.0
info:
  title: Fieldguide api files 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: files
  description: Endpoints used to interact with Fieldguide Files
paths:
  /v1/files/{uuid}:
    delete:
      operationId: delete_file_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the file to delete
        schema:
          format: uuid
          type: string
      responses:
        '204':
          description: No content. The file was deleted successfully.
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `requests.files:write` for request files, `engagements.files:write` for engagement files)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Delete the specified File
      tags:
      - files
    get:
      operationId: get_file_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the File to get details for
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The File details
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Get details for a specific File
      tags:
      - files
      x-required-scopes:
      - files:read
  /v1/files/{uuid}/context:
    get:
      operationId: get_file_context_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the File
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The File context
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileContextRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Get context for a specific File
      tags:
      - files
      x-required-scopes:
      - files:read
  /v1/engagements/{uuid}/folders:
    get:
      operationId: list_engagement_folders_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Engagement for which to get Folders
        schema:
          format: uuid
          type: string
      - name: parent_folder_uuid
        required: false
        in: query
        description: An optional UUID of the parent folder
        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 list of Engagement Folders
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EngagementFolderRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `engagements.files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: List Folders that belong to the specified Engagement
      tags:
      - files
      x-required-scopes:
      - engagements.files:read
  /v1/engagements/{engagement_uuid}/folders/{folder_uuid}:
    get:
      operationId: get_engagement_folder_v1
      parameters:
      - name: engagement_uuid
        required: true
        in: path
        description: The UUID of the Engagement from which to get a Folder
        schema:
          format: uuid
          type: string
      - name: folder_uuid
        required: true
        in: path
        description: The UUID of the folder to fetch
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The Engagement Folder with the specified UUID
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EngagementFolderRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `engagements.files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Fetch a Folder by Engagement and Folder UUIDs
      tags:
      - files
      x-required-scopes:
      - engagements.files:read
  /v1/engagements/{engagement_uuid}/files/{file_uuid}:
    get:
      operationId: get_engagement_file_v1
      parameters:
      - name: engagement_uuid
        required: true
        in: path
        description: The UUID of the Engagement from which to get a File
        schema:
          format: uuid
          type: string
      - name: file_uuid
        required: true
        in: path
        description: The UUID of the File to fetch
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The Engagement File with the specified UUID
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EngagementFileRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `engagements.files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Fetch a File by Engagement and File UUIDs
      tags:
      - files
      x-required-scopes:
      - engagements.files:read
  /v1/engagements/{uuid}/files:
    get:
      operationId: list_engagement_files_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Engagement for which to get Files
        schema:
          format: uuid
          type: string
      - name: folder_uuid
        required: false
        in: query
        description: An optional UUID of the Folder to filter Files by
        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 list of Engagement Files
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EngagementFileRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `engagements.files:read`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: List Files that belong to the specified Engagement
      tags:
      - files
      x-required-scopes:
      - engagements.files:read
    post:
      operationId: upload_engagement_file_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Engagement to upload the File to
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        description: The File to upload
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EngagementFileCreate'
      responses:
        '200':
          description: The UUID of the File that was attached to the Engagement
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/EngagementFileRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `engagements.files:write`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Upload a File to the specified Engagement
      tags:
      - files
      x-required-scopes:
      - engagements.files:write
  /v1/requests/{uuid}/files:
    get:
      operationId: list_request_files_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the Request to list Files 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 Files for the specified Request
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileRead'
        '401':
          description: Unauthorized
        '403':
          description: 'Forbidden


            Forbidden (requires scopes `requests.files:read`)'
        '404':
          description: Resource not found
      summary: Fetch the Files for the specified Request
      tags:
      - files
      x-required-scopes:
      - requests.files:read
    post:
      operationId: upload_request_file_v1
      parameters:
      - name: uuid
        required: true
        in: path
        description: The UUID of the request to upload the file to
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        description: File to upload to the Request
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileCreate'
      responses:
        '200':
          description: The UUID of the file that was attached to the Request
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/FileUploadRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (requires scopes `requests.files:write`)
        '404':
          description: Resource not found
        '429':
          description: Too many requests
      summary: Upload a File to the specified Request
      tags:
      - files
      x-required-scopes:
      - requests.files:write
components:
  schemas:
    EngagementFileReadLinks:
      type: object
      properties:
        fieldguide:
          description: A URL the user can visit to view the Engagement File within the Fieldguide web application
          example:
            href: https://app.fieldguide.io/v1/engagements/2/documents?folder=0d7c72ee-28b3-4bc8-aea1-18bc7d9a8679&file=9b560ead-2b64-41f2-b9ae-826bdb866f1a
            title: Get the result of this job
            type: application/json
          allOf:
          - $ref: '#/components/schemas/HalLink'
      required:
      - fieldguide
    EngagementFolderRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 821e8d9e-d2a8-480f-9187-5a685d3d0d71
          description: The unique identifier for the resource
        parent_folder_uuid:
          type: string
          format: uuid
          example: 721e8d9e-d2a8-480f-9187-5a685d3d0d71
          description: The folder that contains this one
          nullable: true
        engagement_uuid:
          type: string
          format: uuid
          example: 921e8d9e-d2a8-480f-9187-5a685d3d0d71
          description: The Engagement this Folder belongs to
        name:
          type: string
          example: Documents
          description: The name of the Folder
        path:
          type: string
          example: /grandparent/parent
          description: The path to the Folder from the Engagement root
        created_at:
          format: date-time
          type: string
          example: '2024-03-19T12:00:00Z'
          description: Timestamp of when the Folder was created
        _links:
          $ref: '#/components/schemas/EngagementFolderReadLinks'
      required:
      - uuid
      - parent_folder_uuid
      - engagement_uuid
      - name
      - path
      - created_at
      - _links
    EngagementFileRead:
      type: object
      properties:
        name:
          type: string
          example: Board of Directors.docx
        size:
          type: number
          example: 137437
        mime_type:
          type: string
          example: application/vnd.openxmlformats-officedocument.wordprocessingml.document
        url:
          type: string
          format: uri
          example: https://example.com/document.docx
          nullable: true
        url_expiration:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
          nullable: true
        uuid:
          type: string
          format: uuid
          example: 91aeda5e-4a3c-4090-90b1-cbf09d4c1ba1
        created_at:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
          nullable: true
        engagement_uuid:
          type: string
          description: The UUID of the Engagement this File is associated with
          format: uuid
        folder_uuid:
          type: string
          description: The UUID of the Folder this File is associated with, or null if it sits at the Engagement root.
          format: uuid
          nullable: true
        _links:
          $ref: '#/components/schemas/EngagementFileReadLinks'
      required:
      - name
      - size
      - mime_type
      - url
      - url_expiration
      - uuid
      - created_at
      - updated_at
      - engagement_uuid
      - folder_uuid
      - _links
    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
    FileRead:
      type: object
      properties:
        name:
          type: string
          example: Board of Directors.docx
        size:
          type: number
          example: 137437
        mime_type:
          type: string
          example: application/vnd.openxmlformats-officedocument.wordprocessingml.document
        url:
          type: string
          format: uri
          example: https://example.com/document.docx
          nullable: true
        url_expiration:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
          nullable: true
        uuid:
          type: string
          format: uuid
          example: 91aeda5e-4a3c-4090-90b1-cbf09d4c1ba1
        created_at:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
          nullable: true
      required:
      - name
      - size
      - mime_type
      - url
      - url_expiration
      - uuid
      - created_at
      - updated_at
    FileCreate:
      type: object
      properties:
        file:
          type: string
          format: binary
      required:
      - file
    FileContextRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 4d50d252-be0c-4d69-b77a-5bbdfef83f54
        type:
          type: string
          enum:
          - engagement
          - request
          example: engagement
          description: The kind of object this file is attached to.
      required:
      - uuid
      - type
    EngagementFileCreate:
      type: object
      properties:
        file:
          type: string
          format: binary
        folder_uuid:
          type: string
          description: The Folder UUID of the Engagement this File is associated with
          format: uuid
      required:
      - file
    EngagementFolderReadLinks:
      type: object
      properties:
        fieldguide:
          description: A URL the user can visit to view the Engagement Folder within the Fieldguide web application
          example:
            href: https://app.fieldguide.io/engagements/123/documents?folder=abc-123
            title: View this Engagement Folder in Fieldguide
            type: text/html
          allOf:
          - $ref: '#/components/schemas/HalLink'
      required:
      - fieldguide
    FileUploadRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 3e11fc6d-ecd0-4673-8a90-aa787ed391ec
      required:
      - uuid
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
externalDocs:
  description: Fieldguide API Documentation
  url: https://fieldguide.io/developers