Avala AI, Inc. Projects API

openapi: 3.2.0
info:
  title: Avala Projects API
  description: '# Authentication


    ## Generating an API Key


    The Avala SDK uses API keys to authenticate requests. You can create and manage your API keys from the

    Settings page of Mission Control.


    Follow these steps to generate a new API key:


    1. Open your settings page by clicking on your user avatar located at the top right-hand corner of any

    Mission Control screen, and select `Settings`.

    2. From the left-hand sub-menu, select `Security & Identity`.

    3. Click on `New API Key`, enter a name for the key, and then click `Create key`.


    The new key will be automatically copied to your clipboard. Please note, for security reasons, the key

    will not be accessible once you close the window. Ensure you store it in a safe location before closing

    the pop-up modal.


    ### Video walkthrough of API key generation


    ## Authenticating with an API Key


    This is the easiest part! Just add a header named `X-Avala-Api-Key` to your requests and set the

    previously generated API Key as the value.'
  termsOfService: https://avala.ai/legal/terms
  contact:
    email: support@avala.ai
  version: v1
servers:
- url: https://api.avala.ai/api/v1
security:
- API_Key: []
- JWT: []
tags:
- name: Projects
  description: To be completed...
paths:
  /projects/{owner_name}/:
    parameters:
    - name: owner_name
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_list
      description: Projects belonging to an owner that are visible to current user.
      parameters:
      - name: name
        in: query
        description: ''
        required: false
        schema:
          type: string
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: The pagination cursor value.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: order
        in: query
        description: Sets the CursorPagination `offset` when `cursor` is also set. e.g. `cursor=...&offset=1`
        schema:
          type: string
      - name: reverse
        in: query
        description: Sets the CursorPagination `reverse` when `cursor` is also set. e.g. `cursor=...&reverse=1`.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - results
                type: object
                properties:
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectBase'
      tags:
      - Projects
      summary: Projects list
      x-summary-source: derived
  /projects/{project_uid}/consensus/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_consensus_list
      description: Return aggregated consensus summary for the project.
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: The pagination cursor value.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - results
                type: object
                properties:
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsensusScore'
      tags:
      - Projects
      summary: Projects consensus list
      x-summary-source: derived
  /projects/{project_uid}/consensus/compute/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: projects_consensus_compute
      description: Dispatch async consensus computation for this project.
      requestBody:
        $ref: '#/components/requestBodies/ConsensusScore'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsensusScore'
      tags:
      - Projects
      summary: Projects consensus compute
      x-summary-source: derived
  /projects/{project_uid}/consensus/config/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_consensus_config_read
      description: Get or update consensus configuration for this project.
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: The pagination cursor value.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - results
                type: object
                properties:
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsensusScore'
      tags:
      - Projects
      summary: Projects consensus config read
      x-summary-source: derived
    put:
      operationId: projects_consensus_config_update
      description: Get or update consensus configuration for this project.
      requestBody:
        $ref: '#/components/requestBodies/ConsensusScore'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsensusScore'
      tags:
      - Projects
      summary: Projects consensus config update
      x-summary-source: derived
  /projects/{project_uid}/consensus/scores/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_consensus_scores
      description: List per-item consensus scores with optional filtering.
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: The pagination cursor value.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - results
                type: object
                properties:
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConsensusScore'
      tags:
      - Projects
      summary: Projects consensus scores
      x-summary-source: derived
  /projects/{project_uid}/quality-targets/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_quality-targets_list
      summary: CRUD for quality targets scoped to a project
      description: 'GET /api/v1/projects/{project_uid}/quality-targets/

        POST /api/v1/projects/{project_uid}/quality-targets/

        GET /api/v1/projects/{project_uid}/quality-targets/{uid}/

        PATCH /api/v1/projects/{project_uid}/quality-targets/{uid}/

        DELETE /api/v1/projects/{project_uid}/quality-targets/{uid}/

        POST /api/v1/projects/{project_uid}/quality-targets/evaluate/'
      parameters:
      - name: ordering
        in: query
        description: Which field to use when ordering the results.
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: The pagination cursor value.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return per page.
        required: false
        schema:
          type: integer
      - name: order
        in: query
        description: Sets the CursorPagination `offset` when `cursor` is also set. e.g. `cursor=...&offset=1`
        schema:
          type: string
      - name: reverse
        in: query
        description: Sets the CursorPagination `reverse` when `cursor` is also set. e.g. `cursor=...&reverse=1`.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                required:
                - results
                type: object
                properties:
                  next:
                    type:
                    - string
                    - 'null'
                    format: uri
                  previous:
                    type:
                    - string
                    - 'null'
                    format: uri
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/QualityTarget'
      tags:
      - Projects
    post:
      operationId: projects_quality-targets_create
      summary: CRUD for quality targets scoped to a project
      description: 'GET /api/v1/projects/{project_uid}/quality-targets/

        POST /api/v1/projects/{project_uid}/quality-targets/

        GET /api/v1/projects/{project_uid}/quality-targets/{uid}/

        PATCH /api/v1/projects/{project_uid}/quality-targets/{uid}/

        DELETE /api/v1/projects/{project_uid}/quality-targets/{uid}/

        POST /api/v1/projects/{project_uid}/quality-targets/evaluate/'
      requestBody:
        $ref: '#/components/requestBodies/QualityTargetCreate'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityTargetCreate'
      tags:
      - Projects
  /projects/{project_uid}/quality-targets/evaluate/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: projects_quality-targets_evaluate
      description: Evaluate all active quality targets for this project right now.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QualityTarget'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityTarget'
      tags:
      - Projects
      summary: Projects quality targets evaluate
      x-summary-source: derived
  /projects/{project_uid}/quality-targets/{uid}/:
    parameters:
    - name: project_uid
      in: path
      required: true
      schema:
        type: string
    - name: uid
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: projects_quality-targets_read
      summary: CRUD for quality targets scoped to a project
      description: 'GET /api/v1/projects/{project_uid}/quality-targets/

        POST /api/v1/projects/{project_uid}/quality-targets/

        GET /api/v1/projects/{project_uid}/quality-targets/{uid}/

        PATCH /api/v1/projects/{project_uid}/quality-targets/{uid}/

        DELETE /api/v1/projects/{project_uid}/quality-targets/{uid}/

        POST /api/v1/projects/{project_uid}/quality-targets/evaluate/'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityTarget'
      tags:
      - Projects
    patch:
      operationId: projects_quality-targets_partial_update
      summary: CRUD for quality targets scoped to a project
      description: 'GET /api/v1/projects/{project_uid}/quality-targets/

        POST /api/v1/projects/{project_uid}/quality-targets/

        GET /api/v1/projects/{project_uid}/quality-targets/{uid}/

        PATCH /api/v1/projects/{project_uid}/quality-targets/{uid}/

        DELETE /api/v1/projects/{project_uid}/quality-targets/{uid}/

        POST /api/v1/projects/{project_uid}/quality-targets/evaluate/'
      requestBody:
        $ref: '#/components/requestBodies/QualityTargetCreate'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityTargetCreate'
      tags:
      - Projects
    delete:
      operationId: projects_quality-targets_delete
      summary: CRUD for quality targets scoped to a project
      description: 'GET /api/v1/projects/{project_uid}/quality-targets/

        POST /api/v1/projects/{project_uid}/quality-targets/

        GET /api/v1/projects/{project_uid}/quality-targets/{uid}/

        PATCH /api/v1/projects/{project_uid}/quality-targets/{uid}/

        DELETE /api/v1/projects/{project_uid}/quality-targets/{uid}/

        POST /api/v1/projects/{project_uid}/quality-targets/evaluate/'
      responses:
        '204':
          description: ''
      tags:
      - Projects
components:
  schemas:
    QualityTarget:
      required:
      - name
      - metric
      - threshold
      type: object
      properties:
        uid:
          title: Uid
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          description: Human-readable name, e.g. 'Max rejection rate'.
          type: string
          maxLength: 255
          minLength: 1
        metric:
          title: Metric
          type: string
          enum:
          - issue_rate
          - acceptance_rate
          - rejection_rate
          - mean_resolution_time
          - critical_issue_count
        operator:
          title: Operator
          type: string
          enum:
          - gt
          - lt
          - gte
          - lte
        threshold:
          title: Threshold
          description: The threshold value. For rates this is 0-1 (e.g. 0.15 = 15%). For counts this is an integer. For time this is seconds.
          type: number
        severity:
          title: Severity
          type: string
          enum:
          - warning
          - critical
        is_active:
          title: Is active
          type: boolean
        notify_webhook:
          title: Notify webhook
          description: Emit a quality.alert webhook event when threshold is breached.
          type: boolean
        notify_emails:
          description: Email addresses to notify (future use).
          type: array
          items:
            title: Notify emails
            type: string
            format: email
            maxLength: 254
            minLength: 1
        last_evaluated_at:
          title: Last evaluated at
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        last_value:
          title: Last value
          description: The last computed metric value.
          type:
          - number
          - 'null'
          readOnly: true
        is_breached:
          title: Is breached
          description: Whether the target is currently breached.
          type: boolean
          readOnly: true
        breach_count:
          title: Breach count
          description: Total number of times this target has been breached.
          type: integer
          readOnly: true
        last_breached_at:
          title: Last breached at
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        updated_at:
          title: Updated at
          type: string
          format: date-time
          readOnly: true
    ProjectBase:
      required:
      - name
      type: object
      properties:
        uid:
          title: Uid
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type: string
          maxLength: 100
          minLength: 1
        task_type:
          title: Task type
          type: string
          enum:
          - image-annotation
          - video-annotation
          - point-cloud-annotation
          - point-cloud-objects
          - data-collection
        status:
          title: Status
          type: string
          enum:
          - pending-approval
          - active
          - paused
          - canceled
          - archived
          - completed
          readOnly: true
        is_active:
          title: Is active
          type: boolean
          readOnly: true
        visibility:
          title: Visibility
          type: string
          enum:
          - public
          - private
        is_imported:
          title: Is imported
          type: boolean
          readOnly: true
        owner_name:
          title: Owner name
          description: The name of the project owner
          type: string
          readOnly: true
        short_description:
          title: Short description
          type: string
          readOnly: true
          minLength: 1
        industry_icon:
          title: Industry icon
          type:
          - string
          - 'null'
          readOnly: true
        task_time_cap_seconds:
          title: Task time cap seconds
          description: Max time allowed per task in seconds. Overrides default task earning time.
          type:
          - integer
          - 'null'
          maximum: 2147483647
          minimum: 0
    ConsensusScore:
      type: object
      properties:
        uid:
          title: Uid
          type: string
          format: uuid
          readOnly: true
        dataset_item_uid:
          title: Dataset item uid
          type: string
          format: uuid
          readOnly: true
        task_name:
          title: Task name
          description: Task type this score applies to (e.g. 'box', 'classification').
          type: string
          readOnly: true
          minLength: 1
        score_type:
          title: Score type
          type: string
          enum:
          - inter_annotator
          readOnly: true
        score:
          title: Score
          description: Overall consensus score for this item (0.0-1.0).
          type: number
          readOnly: true
        annotator_count:
          title: Annotator count
          description: Number of distinct annotators compared.
          type: integer
          readOnly: true
        details:
          title: Details
          description: 'Score breakdown. For spatial: {mean_iou, matched_pairs, unmatched_count}. For classification: {agreement_ratio, majority_label, label_distribution}.'
          type: object
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    QualityTargetCreate:
      required:
      - name
      - metric
      - threshold
      type: object
      properties:
        name:
          title: Name
          description: Human-readable name, e.g. 'Max rejection rate'.
          type: string
          maxLength: 255
          minLength: 1
        metric:
          title: Metric
          type: string
          enum:
          - issue_rate
          - acceptance_rate
          - rejection_rate
          - mean_resolution_time
          - critical_issue_count
        operator:
          title: Operator
          type: string
          enum:
          - gt
          - lt
          - gte
          - lte
        threshold:
          title: Threshold
          description: The threshold value. For rates this is 0-1 (e.g. 0.15 = 15%). For counts this is an integer. For time this is seconds.
          type: number
        severity:
          title: Severity
          type: string
          enum:
          - warning
          - critical
        is_active:
          title: Is active
          type: boolean
        notify_webhook:
          title: Notify webhook
          description: Emit a quality.alert webhook event when threshold is breached.
          type: boolean
        notify_emails:
          description: Email addresses to notify (future use).
          type: array
          items:
            title: Notify emails
            type: string
            format: email
            maxLength: 254
            minLength: 1
  requestBodies:
    QualityTargetCreate:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QualityTargetCreate'
      required: true
    ConsensusScore:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConsensusScore'
      required: true
  securitySchemes:
    JWT:
      type: apiKey
      name: Authorization
      in: header
      description: JWT token with 'JWT' prefix, e.g., 'JWT eyJhbGciOiJIUzI1NiIsInR...'
    API_Key:
      type: apiKey
      name: X-Avala-Api-Key
      in: header
      description: API key for authentication. Generate one in Mission Control Settings > Security & Identity.