components:
  parameters:
    fields:
      description: List of comma separated model fields to return only.
      in: query
      name: fields
      schema:
        pattern: (\w+)(,\w+)*
        type: string
    filter:
      description: >-
        Filter operations on fields are available with query parameters giving
        field name and operator. Available operators are `eq`, `lt`, `lte`,
        `gt`, `gte`, `ne`, `like`, `ilike`, `icontains`, `isnull`, `in`,
        `notin`. The `like` operator is case-sensitive and takes a `%` wildcard.
        ``ilike` is the same as `like` but case-insensitive. icontains` performs
        a case-insensitive `query searching only for matching substrings.
        isnull` accepts `0` for IS NOT NULL, `and everything else for IS NULL.
        like`, `ilike`, and `icontains` operations are only available for string
        fields.
      in: query
      name: '{field}__{operator}'
      schema:
        type: string
    filter_exact:
      description: Shorthand for {field}__eq filter.
      in: query
      name: '{field}'
      schema:
        type: string
    limit:
      description: Limit parameter for paging output.
      in: query
      name: limit
      schema:
        format: integer
        type: number
    offset:
      description: Offset parameter for paging output.
      in: query
      name: offset
      schema:
        format: integer
        type: number
    sort:
      description: >-
        Sort specification, can be <field> (ascending order) or -<field>
        (descending order).
      in: query
      name: sort
      schema:
        pattern: '[+-]?\w+'
        type: string
  schemas:
    Error:
      additionalProperties: false
      properties:
        errors:
          additionalProperties: {}
          type: object
        message:
          type: string
        status:
          type: integer
        success:
          default: false
      type: object
    ListMeta:
      properties:
        args:
          description: |2-

                        Dictionary reflecting the request parameters.
                        Parameters with default values will be given with
                        their default even it not present in the request.
          type: object
        count:
          description: Count of total available results.
          format: int64
          type: integer
        next:
          description: URL to next page of results.
          type: string
        prev:
          description: URL to previous page of results.
          type: string
      type: object
    QuotaReservation:
      additionalProperties: false
      properties:
        amount:
          nullable: true
        aoi_ref:
          type: string
        collection_id:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          type: integer
        organization_id:
          type: integer
        product_id:
          type: integer
        state:
          type: string
        updated_at:
          format: date-time
          type: string
        url:
          readOnly: true
        user_id:
          type: integer
      type: object
    QuotaReservationBulkRelease:
      additionalProperties: false
      properties:
        collection_id:
          description: >-
            Collection ID in either full ref format
            (pl:features/my/collection-hash) or short hash format
            (collection-hash)
          type: string
        ids:
          items:
            type: integer
          type: array
      type: object
    QuotaReservationCreate:
      additionalProperties: false
      properties:
        aoi_refs:
          description: List of area of interest references
          items:
            type: string
          type: array
        collection_id:
          description: >-
            Collection ID in either full ref format
            (pl:features/my/collection-hash) or short hash format
            (collection-hash)
          type: string
        product_id:
          description: Product ID from /my/products endpoint
          type: integer
      type: object
    QuotaReservationCreated:
      additionalProperties: false
      properties:
        quota_remaining:
          readOnly: true
        quota_reservations:
          items:
            $ref: '#/components/schemas/QuotaReservationCreatedRef'
          type: array
        quota_total:
          readOnly: true
        quota_units:
          readOnly: true
        quota_used:
          readOnly: true
        url:
          readOnly: true
      required:
        - quota_remaining
        - quota_total
        - quota_used
      type: object
    QuotaReservationCreatedRef:
      additionalProperties: false
      properties:
        aoi_ref:
          type: string
        id:
          type: integer
        quota_used:
          type: number
        state:
          type: string
      type: object
    QuotaReservationEstimation:
      additionalProperties: false
      properties:
        estimated_costs:
          description: Breakdown of costs per AOI ref in display units
          readOnly: true
        quota_remaining:
          description: >-
            Remaining quota after existing reservations (excludes this
            estimate's cost) in display units
          readOnly: true
        quota_total:
          description: >-
            Total quota originally allocated to this product access in display
            units
          readOnly: true
        quota_units:
          description: Display units of measurement (e.g., 'sqkm', 'hectare')
          readOnly: true
        total_cost:
          description: Total quota cost for all requested AOI refs in display units
          readOnly: true
      type: object
    QuotaReservationEstimationCost:
      additionalProperties: false
      properties:
        aoi_ref:
          type: string
        cost:
          type: number
      required:
        - aoi_ref
        - cost
      type: object
    QuotaReservationJob:
      additionalProperties: false
      properties:
        collection_id:
          type: string
        id:
          type: integer
        organization_id:
          type: integer
        percentage:
          type: number
        processed_items:
          type: integer
        status:
          type: string
        total_items:
          type: integer
        type:
          type: string
      type: object
    QuotaReservationProduct:
      additionalProperties: false
      properties:
        description:
          type: string
        edp_id:
          type: string
        title:
          type: string
      type: object
    QuotaReservationPubSubMessage:
      additionalProperties: false
      properties:
        action:
          type: string
        aoi_refs:
          items:
            type: string
          nullable: true
          type: array
        collection_id:
          nullable: true
          type: string
        job_id:
          nullable: true
          type: integer
        quota_reservation_ids:
          items:
            type: integer
          nullable: true
          type: array
        user_id:
          nullable: true
          type: integer
      required:
        - action
      type: object
info:
  description: Query and manage quota and product access related data
  title: Quota API
  version: 1.0.0
openapi: 3.0.2
paths:
  /account/v1/quota-reservations/:
    get:
      description: >
        Retrieve a paginated list of quota reservations for the current
        organization.

        Supports filtering, sorting, and field selection.
      parameters:
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/filter_exact'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                  results:
                    items:
                      $ref: '#/components/schemas/QuotaReservation'
                    type: array
                type: object
          description: List of quota reservations retrieved successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request - Invalid query parameters
      summary: Get all quota reservations
      tags:
        - QuotaReservations
    post:
      description: >
        Create a quota reservation for the specified product and area of
        interest references.

        Use the product_id parameter which corresponds to the 'id' field
        returned from the /my/products endpoint.
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Basic quota reservation
                value:
                  aoi_refs:
                    - aoi_123
                    - aoi_456
                  product_id: 12345
            schema:
              $ref: '#/components/schemas/QuotaReservationCreate'
        description: The quota reservation to create
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaReservationCreated'
          description: Quota reservation created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request - Invalid input or insufficient quota
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden - Insufficient permissions
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: >-
            Service Unavailable - Spatial features service (geocorn) is
            unreachable or returned incomplete results. Safe to retry with
            backoff.
      summary: Create a quota reservation
      tags:
        - QuotaReservations
  /account/v1/quota-reservations/bulk-reserve:
    post:
      description: >
        Submit a bulk request to create quota reservations. This operation is
        processed

        asynchronously and returns a job ID to track the progress.

        The product_id parameter corresponds to the 'id' field returned from the
        /my/products endpoint.
      requestBody:
        content:
          application/json:
            examples:
              bulk:
                summary: Bulk quota reservation
                value:
                  aoi_refs:
                    - aoi_123
                    - aoi_456
                    - aoi_789
                  collection_id: my-collection-3qjDEZD
                  product_id: 12345
            schema:
              $ref: '#/components/schemas/QuotaReservationCreate'
        description: The bulk quota reservations to create
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  job_id:
                    description: ID to track the async job
                    type: string
                  status:
                    description: Current job status
                    example: pending
                    type: string
                type: object
          description: Bulk reservation job created successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request - Invalid input or insufficient quota
      summary: Create bulk quota reservations asynchronously
      tags:
        - QuotaReservations
  /account/v1/quota-reservations/estimate:
    post:
      description: >
        Calculate an estimate for quota usage given a product and list of area
        of interest (AOI) references.

        This endpoint helps users understand the quota cost of their intended
        reservations before actually

        creating them. It does NOT create any reservations or modify quota - it
        only provides estimates.


        The product_id parameter corresponds to the 'id' field returned from the
        /my/products endpoint.


        If using collection_id, it can be provided in either full ref format
        (pl:features/my/collection-hash)

        or short hash format (collection-hash).


        **Important**: The quota_remaining field shows your current available
        quota and does NOT subtract

        the cost of the AOIs being estimated. To determine if you have
        sufficient quota for the request,

        compare total_cost against quota_remaining.


        **Response fields**:


        - **total_cost** (float): The total quota cost for all requested AOI
        refs in this estimate.
          This is the sum of all individual AOI costs and represents how much quota would be
          consumed if you were to reserve all the requested AOIs.

        - **quota_remaining** (float): Your current available quota after
        accounting for all existing
          reservations. This value does NOT include/subtract the cost of the AOIs being estimated.
          May be null if the product has unlimited quota.

        - **quota_total** (float): The total quota originally allocated to this
        product access.
          This is your quota limit before any reservations. May be null if unlimited.

        - **estimated_costs** (array): Detailed breakdown of quota costs per AOI
        ref. Each item contains:
          - aoi_ref (string): The AOI reference
          - cost (float): The quota cost for this specific AOI

        - **quota_units** (string): The units of measurement for all quota
        values (e.g., "square_meter").


        **Example usage**:

        If quota_total=1000, quota_remaining=700 (meaning 300 already reserved),
        and total_cost=500,

        then you have sufficient quota since 500 < 700. After reservation,
        quota_remaining would be 200.
      requestBody:
        content:
          application/json:
            examples:
              estimate:
                summary: Quota estimation request
                value:
                  aoi_refs:
                    - aoi_123
                    - aoi_456
                  product_id: 12345
            schema:
              $ref: '#/components/schemas/QuotaReservationCreate'
        description: The product and AOI refs to estimate
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                insufficient_quota:
                  summary: Example with insufficient quota
                  value:
                    estimated_costs:
                      - aoi_ref: aoi_789
                        cost: 800000
                    quota_remaining: 200000
                    quota_total: 1000000
                    quota_units: square_meter
                    total_cost: 800000
                sufficient_quota:
                  summary: Example with sufficient quota
                  value:
                    estimated_costs:
                      - aoi_ref: aoi_123
                        cost: 200000
                      - aoi_ref: aoi_456
                        cost: 300000
                    quota_remaining: 700000
                    quota_total: 1000000
                    quota_units: square_meter
                    total_cost: 500000
                unlimited_quota:
                  summary: Example with unlimited quota
                  value:
                    estimated_costs:
                      - aoi_ref: aoi_123
                        cost: 500000
                    quota_remaining: null
                    quota_total: null
                    quota_units: square_meter
                    total_cost: 500000
              schema:
                $ref: '#/components/schemas/QuotaReservationEstimation'
          description: Quota estimate calculated successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad Request - Invalid input or AOI refs outside coverage boundary
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: >-
            Service Unavailable - Spatial features service (geocorn) is
            unreachable or returned incomplete results. Safe to retry with
            backoff.
      summary: Calculate quota reservation estimate without creating reservations
      tags:
        - QuotaReservations
  /account/v1/quota-reservations/jobs:
    get:
      description: Get all jobs as paginated list. If successful, returns a list of jobs.
      parameters:
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/filter_exact'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  meta:
                    $ref: '#/components/schemas/ListMeta'
                  results:
                    items:
                      $ref: '#/components/schemas/QuotaReservationJob'
                    type: array
                type: object
          description: A list representation of all jobs.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: An error such as validation problems.
      summary: Get all jobs as a paginated list.
      tags:
        - QuotaReservations
  /account/v1/quota-reservations/spec: {}