Fieldguide Insights API

openapi: 3.2.0
info:
  title: Fieldguide Insights API
  description: An API for interacting with the Fieldguide platform
  version: v1
  contact: {}
servers:
- url: https://api.fieldguide.io
  description: Fieldguide API
security:
- bearer: []
tags:
- name: Insights
  description: Endpoints used to interact with Fieldguide Insights
paths:
  /v1/insights/teams/time-tracking/exports/{uuid}:
    get:
      operationId: get_time_tracking_export_v1
      parameters:
      - name: uuid
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The exported Time Tracking Insights file metadata and download URL
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/TimeTrackingFileRead'
        '204':
          description: 'No Time Tracking Insights available


            No Content (the requested timeframe did not generate any results)'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: 'Forbidden


            Forbidden (requires scopes `insights:read`)'
        '429':
          description: Too many requests
      summary: Fetch a generated Insights Time Tracking report
      tags:
      - Insights
      x-required-scopes:
      - insights:read
  /v1/insights/teams/time-tracking/export:
    post:
      description: 'Begins a long-running process that will generate an Insights Time Tracking report in CSV format.


        Use the Job ID that this endpoint returns with the appropriate jobs endpoint to check its status and get its result.'
      operationId: export_time_tracking_report_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeTrackingFileCreate'
      responses:
        '202':
          headers:
            Location:
              description: The URI to check the status of the job
              schema:
                type: string
                example: https://api.fieldguide.io/v1/jobs/f2c75e84-6b42-452d-b52f-3bf1854432d6
            Retry-After:
              description: A date-time estimate of when the job will complete (if the job is still running)
              schema:
                type: string
                format: date-time
                example: '2025-04-04T12:30:00.000Z'
              required: false
          description: The Job UUID for the time tracking export
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/JobSubmittedRead'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: 'Forbidden


            Forbidden (requires scopes `insights:read`)'
        '429':
          description: Too many requests
      summary: Export an Insights Time Tracking report
      tags:
      - Insights
      x-required-scopes:
      - insights:read
components:
  schemas:
    TimeTrackingFileRead:
      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
          - 'null'
          format: uri
          example: https://example.com/document.docx
        url_expiration:
          type:
          - string
          - 'null'
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
        report_data_processed_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2023-01-01T12:30:00.000Z'
        record_count:
          type: number
          example: 1000
      required:
      - name
      - size
      - mime_type
      - url
      - url_expiration
      - report_data_processed_at
      - record_count
    JobSubmittedReadLinks:
      type: object
      properties:
        status:
          description: An API endpoint to retrieve the status of the job
          example:
            href: https://api.fieldguide.io/jobs/2d2e102e-f4af-4534-9749-4d9249eca6cc
            title: Get the status of this job
            type: application/json
          allOf:
          - $ref: '#/components/schemas/HalLink'
      required:
      - status
    JobSubmittedRead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: The UUID of the job that was submitted
        _links:
          $ref: '#/components/schemas/JobSubmittedReadLinks'
      required:
      - 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
    TimeTrackingFileCreate:
      type: object
      properties:
        report_start:
          type: string
          example: '2025-01-01T12:30:00.000Z'
        report_end:
          type: string
          example: '2025-01-01T12:30:00.000Z'
      required:
      - report_start
      - report_end
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
externalDocs:
  description: Fieldguide API Documentation
  url: https://fieldguide.io/developers