public-api.yaml

openapi: 3.0.3
info:
  title: Groundlight API
  version: 0.18.2
  description: Groundlight makes it simple to understand images. You can easily create
    computer vision detectors just by describing what you want to know using natural
    language.
  contact:
    name: support@groundlight.ai
    email: support@groundlight.ai
paths:
  /v1/actions/detector/{detector_id}/rules:
    get:
      operationId: List detector rules
      description: List all rules for a detector
      parameters:
      - in: path
        name: detector_id
        schema:
          type: string
        required: true
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      tags:
      - actions
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRuleList'
          description: ''
    post:
      operationId: Create rule
      description: Create a new rule for a detector
      parameters:
      - in: path
        name: detector_id
        schema:
          type: string
        required: true
      tags:
      - actions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RuleRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RuleRequest'
        required: true
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
          description: ''
  /v1/actions/rules:
    get:
      operationId: List rules
      description: Lists all rules over all detectors owned by the requester.
      parameters:
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: predictor_id
        schema:
          type: string
        description: Filter rules by predictor ID
      tags:
      - actions
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRuleList'
          description: ''
  /v1/actions/rules/{id}:
    get:
      operationId: Get rule
      description: Retrieve a rule
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - actions
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
          description: ''
    delete:
      operationId: Delete rule
      description: Delete a rule
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - actions
      security:
      - ApiToken: []
      responses:
        '204':
          description: No response body
  /v1/detector-groups:
    get:
      operationId: Get Detector Groups
      description: List all detector groups
      tags:
      - detector-groups
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DetectorGroup'
          description: ''
    post:
      operationId: Create Detector Group
      description: |-
        Create a new detector group

        POST data:
          Required:
            - name (str) - name of the predictor set
      tags:
      - detector-groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetectorGroupRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DetectorGroupRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DetectorGroupRequest'
        required: true
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectorGroup'
          description: ''
  /v1/detector-reset/{id}:
    delete:
      operationId: Reset detector
      description: Deletes all image queries on the detector
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - detector-reset
      security:
      - ApiToken: []
      responses:
        '204':
          description: No response body
  /v1/detectors:
    get:
      operationId: List detectors
      description: Retrieve a list of detectors.
      parameters:
      - in: query
        name: page
        schema:
          type: integer
        description: A page number within the paginated result set.
      - in: query
        name: page_size
        schema:
          type: integer
        description: Number of items to return per page.
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDetectorList'
          description: ''
    post:
      operationId: Create detector
      description: Create a new detector.
      tags:
      - detectors
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetectorCreationInputRequest'
        required: true
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detector'
          description: ''
  /v1/detectors/{detector_id}/metrics:
    get:
      operationId: get detector metrics
      description: Get Detector metrics, primarily the counts of different types of
        labels
      parameters:
      - in: path
        name: detector_id
        schema:
          type: string
        required: true
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      num_ground_truth:
                        type: integer
                      num_current_source_human:
                        type: integer
                      class_counts:
                        type: object
                        properties:
                          source_ml:
                            type: object
                          source_human:
                            type: object
                          cloud_labeler:
                            type: object
                          cloud:
                            type: object
                          total:
                            type: object
                      unconfident_counts:
                        type: object
                      total_iqs:
                        type: integer
                    nullable: true
          description: ''
  /v1/detectors/{detector_id}/pipelines:
    get:
      operationId: List detector pipelines
      description: List all MLPipelines for a detector.
      parameters:
      - in: path
        name: detector_id
        schema:
          type: string
        required: true
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: search
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedMLPipelineList'
          description: ''
  /v1/detectors/{id}:
    get:
      operationId: Get detector
      description: Retrieve a detector by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Choose a detector by its ID.
        required: true
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detector'
          description: ''
    patch:
      operationId: Update detector
      description: Update a detector
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - detectors
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedDetectorRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedDetectorRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedDetectorRequest'
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detector'
          description: ''
    delete:
      operationId: Delete detector
      description: Delete a detector by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Choose a detector by its ID.
        required: true
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '204':
          description: No response body
  /v1/detectors/{id}/evaluation:
    get:
      operationId: get detector evaluation
      description: Get Detector evaluation results. The result is null if there isn't
        enough ground truth data to evaluate the detector. Returns the time of the
        evaulation, total ground truth labels, the ml based kfold accuracies, and
        the system accuracies at different confidence thresholds
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - detectors
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  evaluation_results:
                    type: object
                    properties:
                      eval_timestamp:
                        type: string
                        format: date-time
                      total_ground_truth_examples:
                        type: integer
                        nullable: true
                      total_labeled_examples:
                        type: integer
                        nullable: true
                      kfold_pooled__balanced_accuracy:
                        type: number
                        format: float
                        nullable: true
                      kfold_pooled__positive_accuracy:
                        type: number
                        format: float
                        nullable: true
                      kfold_pooled__negative_accuracy:
                        type: number
                        format: float
                        nullable: true
                      precision__mean:
                        type: number
                        format: float
                        nullable: true
                      recall__mean:
                        type: number
                        format: float
                        nullable: true
                      roc_auc__mean:
                        type: number
                        format: float
                        nullable: true
                      balanced_system_accuracies:
                        type: object
                        additionalProperties: true
                        nullable: true
                      positive_system_accuracies:
                        type: object
                        additionalProperties: true
                        nullable: true
                      negative_system_accuracies:
                        type: object
                        additionalProperties: true
                        nullable: true
                      mean_absolute_error__mean:
                        type: number
                        format: float
                        nullable: true
                      objdet_precision__mean:
                        type: number
                        format: float
                        nullable: true
                      objdet_recall__mean:
                        type: number
                        format: float
                        nullable: true
                      objdet_f1_score__mean:
                        type: number
                        format: float
                        nullable: true
                      class_accuracies:
                        type: object
                        additionalProperties: true
                        nullable: true
                      confusion_dict:
                        type: object
                        additionalProperties: true
                        nullable: true
                      num_examples_per_class:
                        type: object
                        additionalProperties: true
                        nullable: true
                    nullable: true
          description: ''
  /v1/edge/fetch-model-urls/{detector_id}/:
    get:
      operationId: Get Model URLs
      description: Gets time limited pre-authenticated URLs to download a detector's
        edge model and oodd model.
      parameters:
      - in: path
        name: detector_id
        schema:
          type: string
        required: true
      tags:
      - edge
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeModelInfo'
          description: ''
  /v1/edge/report-metrics:
    post:
      operationId: edge_report_metrics_create
      description: |-
        Edge server periodically calls this to report metrics.

        POST body will have JSON data that we log.
      tags:
      - edge
      security:
      - ApiToken: []
      responses:
        '200':
          description: No response body
  /v1/image-queries:
    get:
      operationId: List image queries
      description: Retrieve a list of image-queries.
      parameters:
      - in: query
        name: detector_id
        schema:
          type: string
        description: Optionally filter image queries by detector ID.
      - in: query
        name: page
        schema:
          type: integer
        description: A page number within the paginated result set.
      - in: query
        name: page_size
        schema:
          type: integer
        description: Number of items to return per page.
      tags:
      - image-queries
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedImageQueryList'
          description: ''
    post:
      operationId: Submit image query
      description: |2

        Submit an image query against a detector.

        You must use `"Content-Type: image/jpeg"` or similar (image/png, image/webp, etc) for the image data. For example:
        ```Bash
        $ curl https://api.groundlight.ai/device-api/v1/image-queries?detector_id=det_abc123 \
            --header "Content-Type: image/jpeg" \
            --data-binary @path/to/filename.jpeg
        ```
      parameters:
      - in: query
        name: confidence_threshold
        schema:
          type: number
          format: float
          minimum: 0
          maximum: 1
        description: The confidence threshold for the image query.
      - in: query
        name: detector_id
        schema:
          type: string
        description: Choose a detector by its ID.
        required: true
      - in: query
        name: human_review
        schema:
          type: string
        description: |-
          If set to `DEFAULT`, use the regular escalation logic (i.e., send the image query for human review if the ML model is not confident).
          If set to `ALWAYS`, always send the image query for human review even if the ML model is confident.
          If set to `NEVER`, never send the image query for human review even if the ML model is not confident.
      - in: query
        name: image_query_id
        schema:
          type: string
        description: The ID to assign to the created image query.
      - in: query
        name: inspection_id
        schema:
          type: string
        description: Associate the image query with an inspection.
      - in: query
        name: metadata
        schema:
          type: string
        description: A dictionary of custom key/value metadata to associate with the
          image query (limited to 1KB).
      - in: query
        name: patience_time
        schema:
          type: number
          format: float
        description: How long to wait for a confident response.
      - in: query
        name: want_async
        schema:
          type: string
        description: If "true" then submitting an image query returns immediately
          without a result. The result will be computed asynchronously and can be
          retrieved later.
      tags:
      - image-queries
      requestBody:
        content:
          image/jpeg:
            schema:
              type: string
              format: binary
          image/jpg:
            schema:
              type: string
              format: binary
          image/png:
            schema:
              type: string
              format: binary
          image/gif:
            schema:
              type: string
              format: binary
          image/webp:
            schema:
              type: string
              format: binary
          image/bmp:
            schema:
              type: string
              format: binary
          image/x-icon:
            schema:
              type: string
              format: binary
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageQuery'
          description: ''
  /v1/image-queries/{id}:
    get:
      operationId: Get image query
      description: Retrieve an image-query by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Choose an image query by its ID.
        required: true
      tags:
      - image-queries
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageQuery'
          description: ''
  /v1/image-queries/{id}/image:
    get:
      operationId: Get image
      description: Retrieve an image by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: Retrieve the image associated with the image query ID.
        required: true
      tags:
      - image-queries
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
          description: ''
  /v1/labels:
    post:
      operationId: create label
      description: |-
        Create a new LabelValue and attach it to an image query. This will trigger
        asynchronous fine-tuner model training.
      tags:
      - labels
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelValueRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LabelValueRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LabelValueRequest'
        required: true
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelValue'
          description: ''
  /v1/me:
    get:
      operationId: Who am I
      description: Retrieve the current user.
      tags:
      - user
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    description: The user's username
          description: ''
  /v1/month-to-date-account-info:
    get:
      operationId: Month-to-date account info
      description: Fetches and returns the account-specific metrics based on the current
        user's group.
      tags:
      - month-to-date-account-info
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountMonthToDateInfo'
          description: ''
  /v1/notes:
    get:
      operationId: get notes
      description: Retrieves all notes from a given detector and returns them in lists,
        one for each note_category.
      parameters:
      - in: query
        name: detector_id
        schema:
          type: string
        description: the detector whose notes to retrieve
        required: true
      tags:
      - notes
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllNotes'
          description: ''
    post:
      operationId: Create note
      description: Creates a new note.
      parameters:
      - in: query
        name: detector_id
        schema:
          type: string
        description: the detector to associate the new note with
        required: true
      tags:
      - notes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NoteRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/NoteRequest'
      security:
      - ApiToken: []
      responses:
        '204':
          description: No response body
  /v1/priming-groups:
    get:
      operationId: List priming groups
      description: List all priming groups either owned by the authenticated user,
        or with is_global=True.
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: search
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      tags:
      - priming-groups
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPrimingGroupList'
          description: ''
    post:
      operationId: Create priming group
      description: |-
        Create a new priming group seeded from an existing trained MLPipeline.

        The cached_vizlogic_key from the source pipeline is copied as the base binary.
        No FK to the source pipeline is stored, so deleting the source detector does
        not affect this priming group.
      tags:
      - priming-groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrimingGroupCreationInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PrimingGroupCreationInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PrimingGroupCreationInputRequest'
        required: true
      security:
      - ApiToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimingGroup'
          description: ''
  /v1/priming-groups/{id}:
    get:
      operationId: Get priming group
      description: Retrieve a priming group by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - priming-groups
      security:
      - ApiToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrimingGroup'
          description: ''
    delete:
      operationId: Delete priming group
      description: Delete a priming group. Only the owning user's account may delete
        it.
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - priming-groups
      security:
      - ApiToken: []
      responses:
        '204':
          description: No response body
components:
  schemas:
    AccountMonthToDateInfo:
      type: object
      description: Account usage information for the current month
      properties:
        iqs:
          type: integer
          description: The number of image queries in the current month.
        escalations:
          type: integer
          description: The number of escalations in the current month.
        active_detectors:
          type: integer
          description: The number of active detectors in the current month.
        iqs_limit:
          type: integer
          nullable: true
          description: The limit on the number of image queries in the current month.
        escalations_limit:
          type: integer
          nullable: true
          description: The limit on the number of escalations in the current month.
        active_detectors_limit:
          type: integer
          nullable: true
          description: The limit on the number of active detectors in the current
            month.
      required:
      - active_detectors
      - active_detectors_limit
      - escalations
      - escalations_limit
      - iqs
      - iqs_limit
      x-internal: true
    AllNotes:
      type: object
      description: |-
        Serializes all notes for a given detector, grouped by type as listed in UserProfile.NoteCategoryChoices
        The fields must match whats in USERPROFILE.NoteCategoryChoices
      properties:
        CUSTOMER:
          type: array
          items:
            $ref: '#/components/schemas/Note'
        GL:
          type: array
          items:
            $ref: '#/components/schemas/Note'
      required:
      - CUSTOMER
      - GL
    BBoxGeometry:
      type: object
      description: Mixin for serializers to handle data in the StrictBaseModel format
      properties:
        left:
          type: number
          format: double
        top:
          type: number
          format: double
        right:
          type: number
          format: double
        bottom:
          type: number
          format: double
        x:
          type: number
          format: double
          readOnly: true
        y:
          type: number
          format: double
          readOnly: true
      required:
      - bottom
      - left
      - right
      - top
      - x
      - y
    BBoxGeometryRequest:
      type: object
      description: Mixin for serializers to handle data in the StrictBaseModel format
      properties:
        left:
          type: number
          format: double
        top:
          type: number
          format: double
        right:
          type: number
          format: double
        bottom:
          type: number
          format: double
      required:
      - bottom
      - left
      - right
      - top
    BlankEnum:
      enum:
      - ''
    Condition:
      type: object
      properties:
        verb:
          type: string
        parameters:
          type: object
          additionalProperties: {}
      required:
      - parameters
      - verb
    ConditionRequest:
      type: object
      properties:
        verb:
          type: string
        parameters:
          type: object
          additionalProperties: {}
      required:
      - parameters
      - verb
    Detector:
      type: object
      description: |-
        Groundlight Detectors provide answers to natural language questions about images.

        Each detector can answer a single question, and multiple detectors can be strung together for
        more complex logic. Detectors can be created through the create_detector method, or through the
        create_[MODE]_detector methods for pro tier users
      properties:
        id:
          type: string
          readOnly: true
          description: A unique ID for this object.
        type:
          allOf:
          - $ref: '#/components/schemas/DetectorTypeEnum'
          readOnly: true
          description: The type of this object.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When this detector was created.
        name:
          type: string
          description: A short, descriptive name for the detector.
          maxLength: 200
        query:
          type: string
          description: A question about the image.
          readOnly: true
        group_name:
          type: string
          readOnly: true
          description: Which group should this detector be part of?
        confidence_threshold:
          type: number
          format: double
          maximum: 1.0
          minimum: 0.0
          default: 0.9
          description: If the detector's prediction is below this confidence threshold,
            send the image query for human review.
        patience_time:
          type: number
          format: double
          maximum: 3600
          minimum: 0
          default: 30.0
          description: How long Groundlight will attempt to generate a confident prediction
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          readOnly: true
          description: Metadata about the detector.
        mode:
          type: string
          readOnly: true
        mode_configuration:
          type: object
          additionalProperties: {}
          nullable: true
          readOnly: true
        status:
          oneOf:
          - $ref: '#/components/schemas/StatusEnum'
          - $ref: '#/components/schemas/BlankEnum'
        escalation_type:
          type: string
      required:
      - created_at
      - group_name
      - id
      - metadata
      - mode
      - mode_configuration
      - name
      - query
      - type
      x-internal: true
    DetectorCreationInputRequest:
      type: object
      description: Helper serializer for validating POST /detectors input.
      properties:
        name:
          type: string
          minLength: 1
          description: A short, descriptive name for the detector.
          maxLength: 200
        query:
          type: string
          minLength: 1
          description: A question about the image.
          maxLength: 300
        group_name:
          type: string
          minLength: 1
          description: Which group should this detector be part of?
          maxLength: 100
        confidence_threshold:
          type: number
          format: double
          maximum: 1.0
          minimum: 0.0
          default: 0.9
          description: If the detector's prediction is below this confidence threshold,
            send the image query for human review.
        patience_time:
          type: number
          format: double
          maximum: 3600
          minimum: 0
          default: 30.0
          description: How long Groundlight will attempt to generate a confident prediction
        pipeline_config:
          type: string
          nullable: true
          description: (Advanced usage) Configuration needed to instantiate a prediction
            pipeline.
          maxLength: 100
        edge_pipeline_config:
          type: string
          nullable: true
          description: (Advanced usage) Configuration for the edge inference pipeline.
            If not specified, the mode's default edge pipeline is used.
          maxLength: 100
        metadata:
          type: string
          minLength: 1
          description: Base64-encoded metadata for the detector. This should be a
            JSON object with string keys. The size after encoding should not exceed
            1362 bytes, corresponding to 1KiB before encoding.
          maxLength: 1362
        mode:
          allOf:
          - $ref: '#/components/schemas/ModeEnum'
          default: BINARY
          description: |-
            Mode in which this detector will work.

            * `BINARY` - BINARY
            * `COUNT` - COUNT
            * `MULTI_CLASS` - MULTI_CLASS
            * `TEXT` - TEXT
            * `BOUNDING_BOX` - BOUNDING_BOX
        mode_configuration:
          oneOf:
          - $ref: '#/components/schemas/CountModeConfiguration'
          - $ref: '#/components/schemas/MultiClassModeConfiguration'
          - $ref: '#/components/schemas/TextModeConfiguration'
          - $ref: '#/components/schemas/BoundingBoxModeConfiguration'
          nullable: true
        priming_group_id:
          type: string
          nullable: true
          minLength: 1
          description: ID of an existing PrimingGroup to associate with this detector
            (optional).
          maxLength: 44
      required:
      - name
      - query
      x-internal: true
    DetectorGroup:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
          maxLength: 100
      required:
      - id
      - name
    DetectorGroupRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
      required:
      - name
    DetectorModeEnum:
      enum:
      - BINARY
      - COUNT
      - MULTI_CLASS
      - TEXT
      - BOUNDING_BOX
      type: string
      description: |-
        * `BINARY` - BINARY
        * `COUNT` - COUNT
        * `MULTI_CLASS` - MULTI_CLASS
        * `TEXT` - TEXT
        * `BOUNDING_BOX` - BOUNDING_BOX
    DetectorTypeEnum:
      enum:
      - detector
      type: string
    EdgeModelInfo:
      type: object
      description: Information for the model running on edge, including temporary
        presigned urls to the model binaries
      properties:
        model_binary_id:
          type: string
        model_binary_url:
          type: string
        oodd_model_binary_id:
          type: string
        oodd_model_binary_url:
          type: string
        pipeline_config: {}
        oodd_pipeline_config: {}
        predictor_metadata: {}
    ImageQuery:
      type: object
      description: ImageQuery objects are the answers to natural language questions
        about images created by detectors.
      properties:
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          readOnly: true
          description: Metadata about the image query.
        id:
          type: string
          readOnly: true
          description: A unique ID for this object.
        type:
          allOf:
          - $ref: '#/components/schemas/ImageQueryTypeEnum'
          readOnly: true
          description: The type of this object.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: When was this detector created?
        query:
          type: string
          readOnly: true
          description: A question about the image.
        detector_id:
          type: string
          readOnly: true
          description: Which detector was used on this image query?
        result_type:
          allOf:
          - $ref: '#/components/schemas/ResultTypeEnum'
          readOnly: true
          description: What type of result are we returning?
        result:
          oneOf:
          - $ref: '#/components/schemas/BinaryClassificationResult'
          - $ref: '#/components/schemas/CountingResult'
          - $ref: '#/components/schemas/MultiClassificationResult'
          - $ref: '#/components/schemas/TextRecognitionResult'
          - $ref: '#/components/schemas/BoundingBoxResult'
          nullable: true
        patience_time:
          type: number
          format: double
          readOnly: true
          description: How long to wait for a confident response.
        confidence_threshold:
          type: number
          format: double
          readOnly: true
          description: Min confidence needed to accept the response of the image query.
        rois:
          type: array
          items:
            $ref: '#/components/schemas/ROI'
          readOnly: true
          nullable: true
          description: An array of regions of interest (bounding boxes) collected
            on image
        text:
          type: string
          nullable: true
          readOnly: true
          description: A text field on image query.
        done_processing:
          type: boolean
          default: false
          description: EDGE ONLY - Whether the image query has completed escalating
            and will receive no new results.
      required:
      - confidence_threshold
      - created_at
      - detector_id
      - id
      - metadata
      - patience_time
      - query
      - result
      - result_type
      - rois
      - text
      - type
      x-internal: true
    ImageQueryTypeEnum:
      enum:
      - image_query
      type: string
    LabelValue:
      type: object
      properties:
        confidence:
          type: number
          format: double
          nullable: true
          readOnly: true
        class_name:
          type: string
          nullable: true
          description: Return a human-readable class name for this label (e.g. YES/NO)
          readOnly: true
        rois:
          type: array
          items:
            $ref: '#/components/schemas/ROI'
          nullable: true
        annotations_requested:
          type: array
          items:
            type: string
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        detector_id:
          type: integer
          nullable: true
          readOnly: true
        source:
          type: string
          readOnly: true
        text:
          type: string
          readOnly: true
          nullable: true
          description: Text annotations
      required:
      - annotations_requested
      - class_name
      - confidence
      - created_at
      - detector_id
      - source
      - text
    LabelValueRequest:
      type: object
      properties:
        label:
          type: string
          writeOnly: true
          nullable: true
        image_query_id:
          type: string
          writeOnly: true
          minLength: 1
        rois:
          type: array
          items:
            $ref: '#/components/schemas/ROIRequest'
          nullable: true
      required:
      - image_query_id
      - label
    MLPipeline:
      type: object
      description: |-
        A single ML pipeline attached to a detector.
        Includes training status and metrics for the Pipeline Details UI.
      properties:
        id:
          type: string
          readOnly: true
        pipeline_config:
          type: string
          description: Get the resolved pipeline config, including defaults.
          readOnly: true
        is_active_pipeline:
          type: boolean
          readOnly: true
          description: If True, this is the pipeline is used for inference, active
            learning, etc. for its parent Predictor.
        is_edge_pipeline:
          type: boolean
          readOnly: true
          description: If True, this pipeline is enabled for edge inference.
        is_unclear_pipeline:
          type: boolean
          readOnly: true
          description: If True, this pipeline is used to train classifier for human
            unclear label prediction.
        is_oodd_pipeline:
          type: boolean
          readOnly: true
          description: If True, this pipeline is used for OODD.
        is_enabled:
          type: boolean
          readOnly: true
          description: If False, this pipeline will not be run for any use case.
        created_at:
          type: string
          format: date-time
          readOnly: true
        trained_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        type:
          type: string
          description: Determine the pipeline type (active, shadow, unclear, oodd).
          readOnly: true
        friendly_name:
          type: string
          nullable: true
          description: Get the friendly name from the MLBinary.
          readOnly: true
        model_binary_id:
          type: string
          nullable: true
        training_in_progress:
          type: object
          additionalProperties: {}
          nullable: true
          description: Check if training is currently in progress for this pipeline.
          readOnly: true
        metrics:
          type: object
          additionalProperties: {}
          description: Get the metrics for this pipeline from MLBinary metadata and
            evaluation results.
          readOnly: true
        eval_mlbinary_key:
          type: string
          nullable: true
          description: Get the MLBinary key that was evaluated.
          readOnly: true
        eval_mlbinary_revision_number:
          type: integer
          nullable: true
          description: Get the revision number of the MLBinary that was evaluated.
          readOnly: true
        eval_mlbinary_friendly_name:
          type: string
          nullable: true
          description: Get the friendly name of the MLBinary that was evaluated.
          readOnly: true
      required:
      - created_at
      - eval_mlbinary_friendly_name
      - eval_mlbinary_key
      - eval_mlbinary_revision_number
      - friendly_name
      - id
      - is_active_pipeline
      - is_edge_pipeline
      - is_enabled
      - is_oodd_pipeline
      - is_unclear_pipeline
      - metrics
      - model_binary_id
      - pipeline_config
      - trained_at
      - training_in_progress
      - type
      x-internal: true
    ModeEnum:
      type: string
      enum:
      - BINARY
      - COUNT
      - MULTI_CLASS
      - TEXT
      - BOUNDING_BOX
    Note:
      type: object
      properties:
        detector_id:
          type: string
          readOnly: true
        content:
          type: string
          nullable: true
          description: Text content of the note.
        is_pinned:
          type: boolean
          nullable: true
      required:
      - detector_id
    NoteRequest:
      type: object
      properties:
        content:
          type: string
          nullable: true
          description: Text content of the note.
        is_pinned:
          type: boolean
          nullable: true
        image:
          type: string
          format: binary
          writeOnly: true
          nullable: true
    NullEnum:
      enum:
      - null
    PaginatedDetectorList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Detector'
    PaginatedImageQueryList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/ImageQuery'
    PaginatedMLPipelineList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/MLPipeline'
    PaginatedPrimingGroupList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/PrimingGroup'
    PaginatedRuleList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
    PatchedDetectorRequest:
      type: object
      description: |-
        Groundlight Detectors provide answers to natural language questions about images.

        Each detector can answer a single question, and multiple detectors can be strung together for
        more complex logic. Detectors can be created through the create_detector method, or through the
        create_[MODE]_detector methods for pro tier users
      properties:
        name:
          type: string
          minLength: 1
          description: A short, descriptive name for the detector.
          maxLength: 200
        confidence_threshold:
          type: number
          format: double
          maximum: 1.0
          minimum: 0.0
          default: 0.9
          description: If the detector's prediction is below this confidence threshold,
            send the image query for human review.
        patience_time:
          type: number
          format: double
          maximum: 3600
          minimum: 0
          default: 30.0
          description: How long Groundlight will attempt to generate a confident prediction
        status:
          oneOf:
          - $ref: '#/components/schemas/StatusEnum'
          - $ref: '#/components/schemas/BlankEnum'
        escalation_type:
          type: string
          minLength: 1
      x-internal: true
    PayloadTemplate:
      type: object
      properties:
        template:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
          nullable: true
      required:
      - template
    PayloadTemplateRequest:
      type: object
      properties:
        template:
          type: string
          minLength: 1
        headers:
          type: object
          additionalProperties:
            type: string
            minLength: 1
          nullable: true
      required:
      - template
    PrimingGroup:
      type: object
      description: A PrimingGroup owned by the authenticated user.
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
          maxLength: 100
        detector_mode:
          nullable: true
          description: |-
            Detector mode this priming group is intended for (BINARY, MULTI_CLASS, etc.). Validated against the pipeline_config of every active and shadow base MLBinary in clean(). Nullable only for legacy rows pre-dating this field; new PrimingGroups must set it.

            * `BINARY` - BINARY
            * `COUNT` - COUNT
            * `MULTI_CLASS` - MULTI_CLASS
            * `TEXT` - TEXT
            * `BOUNDING_BOX` - BOUNDING_BOX
          oneOf:
          - $ref: '#/components/schemas/DetectorModeEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
        num_classes:
          type: integer
          readOnly: true
          nullable: true
          description: Number of output classes this priming group is trained for.
            Set automatically from the source predictor when created via create_user_priming_group
            (MULTI_CLASS only). Nullable for legacy rows and for modes where class
            count isn't meaningful; a follow-up PR will tighten this after manual
            backfill.
        is_global:
          type: boolean
          readOnly: true
          description: If True, this priming group is shared to all Groundlight users.
            Can only be set by Groundlight admins.
        canonical_query:
          type: string
          nullable: true
          description: Canonical semantic query for this priming group
          maxLength: 300
        active_pipeline_config:
          type: string
          nullable: true
          description: Active pipeline config override for new detectors created in
            this priming group. If set, this overrides the default active pipeline
            config at creation time.Can be either a pipeline name or full config string.
          maxLength: 8192
        priming_group_specific_shadow_pipeline_configs:
          nullable: true
          description: 'Configs for shadow pipelines to create for detectors in this
            priming group. These are added to the default shadow pipeline configs
            for a detector of the given mode. Each entry is either a pipeline name
            or full config string. '
        disable_shadow_pipelines:
          type: boolean
          description: If True, new detectors added to this priming group will not
            receive the mode-specific default shadow pipelines from INITIAL_SHADOW_PIPELINE_CONFIG_SET.
            Priming-group-specific shadow configs still apply. Use this to guarantee
            the primed active MLBinary is never switched off by a shadow pipeline
            being promoted.
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - created_at
      - id
      - is_global
      - name
      - num_classes
      x-internal: true
    PrimingGroupCreationInputRequest:
      type: object
      description: Input for creating a new user-owned PrimingGroup seeded from an
        existing MLPipeline.
      properties:
        name:
          type: string
          minLength: 1
          description: Name for the new priming group.
          maxLength: 100
        source_ml_pipeline_id:
          type: string
          minLength: 1
          description: ID of an MLPipeline owned by this account whose trained model
            will seed the priming group.
          maxLength: 44
        detector_mode:
          allOf:
          - $ref: '#/components/schemas/DetectorModeEnum'
          description: |-
            Detector mode this priming group is intended for (BINARY, MULTI_CLASS, etc.). Must match the mode supported by the source MLPipeline's pipeline_config.

            * `BINARY` - BINARY
            * `COUNT` - COUNT
            * `MULTI_CLASS` - MULTI_CLASS
            * `TEXT` - TEXT
            * `BOUNDING_BOX` - BOUNDING_BOX
        canonical_query:
          type: string
          nullable: true
          description: Optional canonical semantic query describing this priming group.
          maxLength: 300
        disable_shadow_pipelines:
          type: boolean
          default: false
          description: If true, new detectors added to this priming group will not
            receive the default shadow pipelines. This guarantees the primed active
            model is never switched off.
      required:
      - detector_mode
      - name
      - source_ml_pipeline_id
      x-internal: true
    ROI:
      type: object
      description: Mixin for serializers to handle data in the StrictBaseModel format
      properties:
        label:
          type: string
          description: The label of the bounding box.
        score:
          type: number
          format: double
          readOnly: true
          description: The confidence of the bounding box.
        geometry:
          $ref: '#/components/schemas/BBoxGeometry'
      required:
      - geometry
      - label
      - score
    ROIRequest:
      type: object
      description: Mixin for serializers to handle data in the StrictBaseModel format
      properties:
        label:
          type: string
          minLength: 1
          description: The label of the bounding box.
        geometry:
          $ref: '#/components/schemas/BBoxGeometryRequest'
      required:
      - geometry
      - label
    ResultTypeEnum:
      enum:
      - binary_classification
      - counting
      - multi_classification
      - text_recognition
      - bounding_box
      type: string
    Rule:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        detector_id:
          type: string
          readOnly: true
        detector_name:
          type: string
          readOnly: true
        name:
          type: string
          maxLength: 44
        enabled:
          type: boolean
          default: true
        snooze_time_enabled:
          type: boolean
          default: false
        snooze_time_value:
          type: integer
          minimum: 0
          default: 0
        snooze_time_unit:
          allOf:
          - $ref: '#/components/schemas/SnoozeTimeUnitEnum'
          default: DAYS
        human_review_required:
          type: boolean
          default: false
        condition:
          $ref: '#/components/schemas/Condition'
        action:
          oneOf:
          - $ref: '#/components/schemas/Action'
          - $ref: '#/components/schemas/ActionList'
        webhook_action:
          type: array
          items:
            $ref: '#/components/schemas/WebhookAction'
      required:
      - condition
      - detector_id
      - detector_name
      - id
      - name
    RuleRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 44
        enabled:
          type: boolean
          default: true
        snooze_time_enabled:
          type: boolean
          default: false
        snooze_time_value:
          type: integer
          minimum: 0
          default: 0
        snooze_time_unit:
          allOf:
          - $ref: '#/components/schemas/SnoozeTimeUnitEnum'
          default: DAYS
        human_review_required:
          type: boolean
          default: false
        condition:
          $ref: '#/components/schemas/ConditionRequest'
        action:
          oneOf:
          - $ref: '#/components/schemas/Action'
          - $ref: '#/components/schemas/ActionList'
        webhook_action:
          type: array
          items:
            $ref: '#/components/schemas/WebhookActionRequest'
      required:
      - condition
      - name
    SnoozeTimeUnitEnum:
      enum:
      - DAYS
      - HOURS
      - MINUTES
      - SECONDS
      type: string
      description: |-
        * `DAYS` - DAYS
        * `HOURS` - HOURS
        * `MINUTES` - MINUTES
        * `SECONDS` - SECONDS
    StatusEnum:
      enum:
      - 'ON'
      - 'OFF'
      type: string
      description: |-
        * `ON` - ON
        * `OFF` - OFF
    WebhookAction:
      type: object
      properties:
        url:
          type: string
          format: uri
          maxLength: 200
        include_image:
          type: boolean
        payload_template:
          allOf:
          - $ref: '#/components/schemas/PayloadTemplate'
          nullable: true
        last_message_failed:
          type: boolean
        last_failure_error:
          type: string
          nullable: true
        last_failed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - url
    WebhookActionRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          minLength: 1
          maxLength: 200
        include_image:
          type: boolean
        payload_template:
          allOf:
          - $ref: '#/components/schemas/PayloadTemplateRequest'
          nullable: true
        last_message_failed:
          type: boolean
        last_failure_error:
          type: string
          nullable: true
        last_failed_at:
          type: string
          format: date-time
          nullable: true
      required:
      - url
    BinaryClassificationResult:
      type: object
      properties:
        confidence:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          nullable: true
        source:
          type: string
        result_type:
          enum:
          - binary_classification
        from_edge:
          type: boolean
        label:
          type: string
      required:
      - label
    CountingResult:
      type: object
      properties:
        confidence:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          nullable: true
        source:
          type: string
        result_type:
          enum:
          - counting
        from_edge:
          type: boolean
        count:
          type: integer
          minimum: 0
          nullable: true
        greater_than_max:
          type: boolean
      required:
      - count
    MultiClassificationResult:
      type: object
      properties:
        confidence:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          nullable: true
        source:
          type: string
        result_type:
          enum:
          - multi_classification
        from_edge:
          type: boolean
        label:
          type: string
          nullable: false
      required:
      - label
    TextRecognitionResult:
      type: object
      properties:
        confidence:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          nullable: true
        source:
          type: string
        result_type:
          enum:
          - text_recognition
        from_edge:
          type: boolean
        text:
          type: string
          nullable: true
        truncated:
          type: boolean
      required:
      - text
      - truncated
    BoundingBoxResult:
      type: object
      properties:
        confidence:
          type: number
          format: float
          minimum: 0.0
          maximum: 1.0
          nullable: true
        source:
          type: string
        result_type:
          enum:
          - bounding_box
        from_edge:
          type: boolean
        label:
          type: string
      required:
      - label
    CountModeConfiguration:
      type: object
      properties:
        max_count:
          type: integer
          minimum: 1
          maximum: 50
          nullable: false
        class_name:
          type: string
          nullable: false
      required:
      - class_name
    MultiClassModeConfiguration:
      type: object
      properties:
        class_names:
          type: array
          items:
            type: string
            nullable: false
        num_classes:
          type: integer
          nullable: false
      required:
      - class_names
    TextModeConfiguration:
      type: object
      properties:
        value_max_length:
          type: integer
          minimum: 1
          maximum: 250
          nullable: false
    BoundingBoxModeConfiguration:
      type: object
      properties:
        class_name:
          type: string
          nullable: false
        max_num_bboxes:
          type: integer
          minimum: 1
          maximum: 50
          nullable: false
      required:
      - class_name
    ChannelEnum:
      type: string
      enum:
      - TEXT
      - EMAIL
    Action:
      type: object
      properties:
        channel:
          $ref: '#/components/schemas/ChannelEnum'
        recipient:
          type: string
        include_image:
          type: boolean
      required:
      - channel
      - recipient
      - include_image
    ActionList:
      type: array
      items:
        $ref: '#/components/schemas/Action'
    AnnotationsRequestedEnum:
      type: string
      enum:
      - BINARY_CLASSIFICATION
      - BOUNDING_BOXES
    EscalationTypeEnum:
      type: string
      enum:
      - STANDARD
      - NO_HUMAN_LABELING
    SourceEnum:
      type: string
      enum:
      - INITIAL_PLACEHOLDER
      - CLOUD
      - CUST
      - HUMAN_CLOUD_ENSEMBLE
      - AI_CLOUD
      - AI_CLOUD_ENSEMBLE
      - HUMAN_AI_CLOUD_ENSEMBLE
      - ALG
      - ALG_REC
      - ALG_UNCLEAR
      - EDGE
    VerbEnum:
      type: string
      enum:
      - ANSWERED_CONSECUTIVELY
      - ANSWERED_WITHIN_TIME
      - CHANGED_TO
      - NO_CHANGE
      - NO_QUERIES
    BoundingBoxLabelEnum:
      type: string
      enum:
      - NO_OBJECTS
      - BOUNDING_BOX
      - GREATER_THAN_MAX
      - UNCLEAR
    Source:
      type: string
      enum:
      - STILL_PROCESSING
      - CLOUD
      - USER
      - CLOUD_ENSEMBLE
      - ALGORITHM
      - AI_CLOUD
      - AI_CLOUD_ENSEMBLE
      - HUMAN_AI_CLOUD_ENSEMBLE
      - EDGE
    Label:
      type: string
      enum:
      - 'YES'
      - 'NO'
      - UNCLEAR
  securitySchemes:
    ApiToken:
      name: x-api-token
      type: apiKey
      in: header
servers:
- url: https://api.groundlight.ai/device-api
  description: Prod
- url: https://api.integ.groundlight.ai/device-api
  description: Integ
- url: https://device.positronix.ai/device-api
  description: Device Prod
- url: https://device.integ.positronix.ai/device-api
  description: Device Integ