# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/quotas.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/quotas.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Quotas API
  version: 1.0.0
  description: >-
    Quotas: the ceilings a project runs under — requests, tokens or cost over a rolling window or a
    calendar month, scoped to the whole project or to one key, agent or end user, and stored bytes
    against the project's whole footprint. A quota either enforces or only watches, so a limit can
    be measured before it bites. A fully runtime-backed module — this spec is generated verbatim
    from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is
    authorized by naturali and enforced upstream by the project's scoped credential.


    This module mirrors the upstream runtime verbatim (tier A): paths are the runtime's own
    re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape
    passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by
    naturali itself (authentication, project resolution, an unreachable runtime) use naturali's.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: "{baseUrl}"
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: Quotas
    description: Manage quotas and rate limits
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/quotas:
    get:
      tags:
        - Quotas
      summary: List quotas
      description: Returns the quotas defined in a project
      operationId: listQuotas
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of quotas
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Quota"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - Quotas
      summary: Create a quota
      description: >-
        Creates a project-scoped quota. `requests` is valid for `scope: project`/`api_key`; `tokens`
        and `cost_usd` are valid for `scope: project`/`agent`/`actor`; `storage_bytes` is valid for
        `scope: project` only. Any other scope/metric pair is rejected with 400 (no attribution
        exists to enforce it). An `actor` quota caps one end user's spend, matched from the
        generation's session; a null `scope_ref` means one budget *per* actor rather than a pooled
        project total. A `cost_usd` quota may name one `meter_type` to cap; omitting it caps every
        priced meter. A duplicate quota (same project, scope, scope_ref, metric, window, meter_type)
        is rejected with 409.


        `storage_bytes` caps a stored total rather than a windowed one, so it takes `window:
        current` and every other metric refuses that value (400 either way). It is enforced at the
        corpus write paths — file upload and create, document create, document ingest and re-ingest,
        memory create — with `409 QUOTA_STORAGE_EXCEEDED` and no `Retry-After`, since no window
        reset clears a footprint.
      operationId: createQuota
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scope
                - metric
                - window
                - limit
              additionalProperties: false
              properties:
                scope:
                  type: string
                  enum:
                    - project
                    - api_key
                    - agent
                    - actor
                  description: The scope the quota applies to
                scope_ref:
                  type: string
                  nullable: true
                  description: Public id of the api key / agent / actor the quota applies to. For `api_key` and
                    `agent` scope, NULL means all entities of that scope type in the project. For
                    `actor` scope, NULL means one budget *per* actor — each end user gets their own
                    allowance — rather than a pooled total across all actors.
                  example: key_V1StGXR8Z5jdHi6B
                metric:
                  type: string
                  enum:
                    - requests
                    - tokens
                    - cost_usd
                    - storage_bytes
                  description: The metric being capped
                  example: requests
                window:
                  type: string
                  enum:
                    - rolling_1m
                    - rolling_1h
                    - rolling_24h
                    - calendar_month
                    - current
                  description: The window over which the metric is aggregated. `current` is the only accepted value
                    for storage_bytes (a stored total is not aggregated over time) and is refused
                    for every other metric.
                limit:
                  type: number
                  description: The cap. Must be a positive integer for requests/tokens/storage_bytes (bytes);
                    fractional values are allowed for cost_usd.
                  example: 600
                mode:
                  type: string
                  enum:
                    - enforce
                    - monitor
                  default: enforce
                  description: enforce blocks with 429 (requests at the middleware, tokens/cost_usd at the
                    pre-generation check); monitor observes without blocking — a breach fires the
                    quotas.exceeded webhook and writes a quotas:MonitorBreach audit entry, but the
                    request is let through.
                  example: enforce
                on_unpriced:
                  type: string
                  enum:
                    - block
                    - allow
                  default: block
                  description: "Only for metric cost_usd (400 on any other metric). What an enforce quota does when
                    the current window is a pricing blackout — several metered llm_tokens events,
                    none of them priced, so the aggregate is 0 however much was actually spent.
                    Platform meters such as compute_execution are read for the aggregate but never
                    for this verdict. block (the default) refuses new generations with 409
                    QUOTA_UNENFORCEABLE until pricing is configured; allow accepts the unmeasurable
                    spend explicitly. Either way a quota_unpriced exception is filed. monitor-mode
                    quotas never block regardless. A partly priced window is not a blackout: no
                    posture refuses it, it is enforced on its priced total, and it files the same
                    exception."
                  example: block
                meter_type:
                  type: string
                  enum:
                    - llm_tokens
                    - compute_execution
                    - api_request
                    - storage
                    - tool_execution
                  description: Only for metric cost_usd (400 on any other metric). The meter this cap answers for.
                    Omit it and the cap sums every priced meter, which is the existing behaviour;
                    name one and only that meter's cost counts, so an AI spend cap is not consumed
                    by platform meters the operator prices (and vice versa). Part of the quota's
                    identity, so two meter scopes can share a scope/metric/window and neither
                    conflicts with an unscoped cap. Immutable after creation — replace the quota to
                    change it.
      responses:
        "201":
          description: Quota created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quota"
        "400":
          description: Bad request (invalid scope/metric/window/mode/limit)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "409":
          description: A matching quota already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/quotas/{quota_id}:
    get:
      tags:
        - Quotas
      summary: Get a quota
      description: Returns a specific quota, including current window usage
      operationId: getQuota
      parameters:
        - name: quota_id
          in: path
          required: true
          description: Quota ID
          schema:
            type: string
            example: quota_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: Quota details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quota"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Quota not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - Quotas
      summary: Update a quota
      description: Updates a quota's limit and/or mode. Other fields are immutable.
      operationId: updateQuota
      parameters:
        - name: quota_id
          in: path
          required: true
          description: Quota ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                limit:
                  type: number
                  description: New limit
                  example: 1000
                mode:
                  type: string
                  enum:
                    - enforce
                    - monitor
                  description: New mode
                  example: monitor
                on_unpriced:
                  type: string
                  enum:
                    - block
                    - allow
                  description: New pricing posture. Only for metric cost_usd (400 on any other metric); see the create
                    operation for what block and allow mean.
                  example: allow
      responses:
        "200":
          description: Quota updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quota"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Quota not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    delete:
      tags:
        - Quotas
      summary: Delete a quota
      description: Deletes a quota and drops its window counters
      operationId: deleteQuota
      parameters:
        - name: quota_id
          in: path
          required: true
          description: Quota ID
          schema:
            type: string
      responses:
        "204":
          description: Quota deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Quota not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    Quota:
      type: object
      properties:
        id:
          type: string
          example: quota_V1StGXR8Z5jdHi6B
        project_id:
          x-naturali-ref: projects
          type: string
        scope:
          type: string
          enum:
            - project
            - api_key
            - agent
            - actor
        scope_ref:
          type: string
          nullable: true
          description: Public id of the api key / agent / actor the quota applies to. For `api_key` and
            `agent` scope, NULL means all entities of that scope type in the project. For `actor`
            scope, NULL means one budget *per* actor rather than a pooled total across all actors.
        metric:
          type: string
          enum:
            - requests
            - tokens
            - cost_usd
            - storage_bytes
        window:
          type: string
          enum:
            - rolling_1m
            - rolling_1h
            - rolling_24h
            - calendar_month
            - current
          description: The window the metric is aggregated over; `current` on storage_bytes, which caps a
            stored total and never resets.
        limit:
          type: number
        mode:
          type: string
          enum:
            - enforce
            - monitor
        meter_type:
          type: string
          enum:
            - llm_tokens
            - compute_execution
            - api_request
            - storage
            - tool_execution
            - null
          nullable: true
          description: The meter a cost_usd cap answers for. Null is every priced meter, which is what a quota
            created without one carries.
        on_unpriced:
          type: string
          enum:
            - block
            - allow
            - null
          nullable: true
          description: Pricing posture of a cost_usd quota over an unpriced blackout — block refuses
            generations, allow lets them through (the quota_unpriced exception is filed either way,
            and for a partly priced window, which no posture refuses). Null for metrics with no
            pricing dependency.
        current_usage:
          type: object
          nullable: true
          description: Current fixed-window usage for the requests metric. Null for token/cost quotas (which
            aggregate the usage meter at check time rather than keeping a counter), null for
            storage_bytes (a stored total has no window and no counter — read the footprint from the
            storage meter), and null in list responses.
          properties:
            window_key:
              type: string
              example: 2026-07-07T12:31Z
            count:
              type: integer
              example: 42
            resets_at:
              type: string
              format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an
        integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`; omit it for the first page. A cursor this list did
        not issue is `400`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: "A connected app's OAuth access token, issued by this API's authorization server
        (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation,
        confined to the projects the user chose when approving the app."
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: "`QUOTA_EXCEEDED` — a `requests` quota on the calling API key or its project is spent
        for the window; `Retry-After` says when it reopens"
      headers:
        Retry-After:
          description: Seconds until the quota window admits a request again
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PayloadTooLarge:
      description: "`REQUEST_REJECTED` — the request body is over the size the body parser accepts"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionUnavailable:
      description: The deployment's admission service is asked about this write and did not answer —
        `ADMISSION_UNAVAILABLE`; the write did not happen
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionRefused:
      description: The deployment's admission service refused this write — answered under the service's
        own `4xx` status, with its `code` (matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`, not necessarily
        an `ERROR_CODES` key), `message` and `meta`; the write did not happen. A status this
        operation also declares on its own is documented there
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Unexpected server error — `INTERNAL_ERROR`, with the raw message never forwarded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProjectNotFound:
      description: The project does not exist or the caller is not a member of it (`RESOURCE_NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
