# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/files.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/files.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — Files API
  version: 1.0.0
  description: >-
    Files: the stored bytes a project works from — uploaded directly or as base64, downloaded raw or
    as base64, tagged, and referenced by a document for ingestion. 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: Files
    description: Manage files
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/files:
    get:
      tags:
        - Files
      summary: List all files
      description: Returns a list of all stored files
      operationId: listFiles
      parameters:
        - name: path_prefix
          in: query
          required: false
          description: "Only files under this directory. The prefix is a path boundary, not a substring:
            `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/`
            selects the whole project. A leading slash is optional and a trailing one is ignored, so
            `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal
            characters, not wildcards. Naming a directory under `/.system/` is what includes
            platform-written files, which a list without this parameter leaves out."
          schema:
            type: string
            example: /reports/
        - $ref: "#/components/parameters/TagsQuery"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of files returned successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/FileRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "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:
        - Files
      summary: Create a file
      description: Creates a new file record in the system
      operationId: createFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prefix:
                  type: string
                  description: Directory within the project (e.g. /images). Optional; defaults to / (root). Combined
                    with filename to form the file's key (path).
                  example: /images
                filename:
                  type: string
                  description: Original / download name and the key's leaf segment (e.g. logo.png).
                  example: logo.png
                content_type:
                  type: string
                  description: MIME type of the file
                  example: application/pdf
                size:
                  type: integer
                  nullable: true
                  description: File size in bytes
                  example: 1024
                metadata:
                  $ref: "#/components/schemas/MetadataBag"
      responses:
        "201":
          description: File created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "409":
          description: The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete
            stored content, or raise the quota — no window reset clears a stored total, so no
            `Retry-After` is sent.
          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}/files/upload:
    post:
      tags:
        - Files
      summary: Upload a file
      description: Uploads a file to the server and stores it in the configured storage directory
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: File content
                prefix:
                  type: string
                  description: Directory within the project (e.g. /images). Optional; defaults to / (root).
                  example: /images
                filename:
                  type: string
                  description: Original / download name. Optional; defaults to the uploaded file's name.
                  example: logo.png
                metadata:
                  $ref: "#/components/schemas/MetadataBagText"
      responses:
        "201":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRecord"
        "400":
          description: Missing file or invalid project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "409":
          description: The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete
            stored content, or raise the quota — no window reset clears a stored total, so no
            `Retry-After` is sent.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: The upload is over this deployment's byte ceiling (`UPLOAD_TOO_LARGE`;
            `FILE_UPLOAD_MAX_BYTES`, 25 MB by default). The request is refused while the body is
            still streaming, so nothing was stored.
          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"
  /v1/projects/{project_id}/files/upload/base64:
    post:
      tags:
        - Files
      summary: Upload a file using base64 encoding
      description: Uploads a file to the server using base64-encoded content
      operationId: uploadFileBase64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadFileBase64Request"
      responses:
        "201":
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRecord"
        "400":
          description: Missing content or invalid project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "409":
          description: The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete
            stored content, or raise the quota — no window reset clears a stored total, so no
            `Retry-After` is sent.
          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"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/files/{file_id}:
    get:
      tags:
        - Files
      summary: Get a file by ID
      description: Returns the data and metadata of a specific file
      operationId: getFile
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
            example: abc123
      responses:
        "200":
          description: File found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      tags:
        - Files
      summary: Delete a file
      description: Removes a file from the system by ID
      operationId: deleteFile
      parameters:
        - name: file_id
          in: path
          required: true
          description: ID of the file to delete
          schema:
            type: string
            example: abc123
      responses:
        "204":
          description: File deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: FILE_HAS_DEPENDENTS — another record still references the file.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "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}/files/{file_id}/download:
    get:
      tags:
        - Files
      summary: Download a file
      description: Streams the file content to the client
      operationId: downloadFile
      x-mcp-exclude: true
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
        - name: token
          in: query
          required: false
          description: Signed single-file download token, an alternative to a bearer credential (issued for
            ingestion-rule converters).
          schema:
            type: string
            example: file_abc123
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/files/{file_id}/metadata:
    patch:
      tags:
        - Files
      summary: Update file metadata
      description: Updates the metadata field of a file
      operationId: updateFileMetadata
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
            example: file_abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                metadata:
                  description: Replaces the stored bag; `null` clears it.
                  allOf:
                    - $ref: "#/components/schemas/NullableMetadataBag"
                prefix:
                  type: string
                  description: New directory — moves the file. The resulting path (prefix + filename) must be unique
                    within the project.
                  example: /reports
                filename:
                  type: string
                  description: New filename — renames the key's leaf and the download name.
                  example: renamed-file.txt
      responses:
        "200":
          description: Metadata updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileRecord"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: A file already exists at the target path in this project
          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"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/files/{file_id}/download/base64:
    get:
      tags:
        - Files
      summary: Download file as base64
      description: Returns the file content encoded as base64
      operationId: downloadFileBase64
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
        - name: token
          in: query
          required: false
          description: Signed single-file download token, an alternative to a bearer credential (issued for
            ingestion-rule converters).
          schema:
            type: string
      responses:
        "200":
          description: File content as base64
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: Base64-encoded file content
                  filename:
                    type: string
                    description: Original filename
                  content_type:
                    type: string
                    description: MIME type of the file
                  size:
                    type: integer
                    nullable: true
                    description: File size in bytes
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/files/{file_id}/tags:
    get:
      tags:
        - Files
      summary: Get file tags
      description: Returns all tags attached to the file
      operationId: getFileTags
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
      responses:
        "200":
          description: File tags
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      tags:
        - Files
      summary: Replace file tags
      description: Replaces all tags on the file with the provided tags
      operationId: replaceFileTags
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags replaced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File 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"
    patch:
      tags:
        - Files
      summary: Merge file tags
      description: Merges provided tags into the file's existing tags (existing tags are preserved unless
        overridden)
      operationId: mergeFileTags
      parameters:
        - name: file_id
          in: path
          required: true
          description: File ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagBag"
      responses:
        "200":
          description: Tags merged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagBag"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: File 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"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    UploadFileBase64Request:
      type: object
      required:
        - content
      additionalProperties: false
      properties:
        content:
          type: string
          description: Base64-encoded file content
          example: SGVsbG8gV29ybGQ=
        prefix:
          type: string
          description: Directory within the project (e.g. /documents). Optional; defaults to / (root).
          example: /documents
        filename:
          type: string
          description: Original / download name and the key's leaf segment.
          example: document.txt
        content_type:
          type: string
          description: MIME type of the file
          example: text/plain
        metadata:
          $ref: "#/components/schemas/MetadataBag"
    FileRecord:
      type: object
      description: Stored file metadata
      properties:
        id:
          type: string
          description: Unique file identifier
          example: abc123
        project_id:
          x-naturali-ref: projects
          type: string
          description: Project the file belongs to. Present on `getFile` and on file events; absent on the
            other operations' records.
          example: proj_V1StGXR8Z5jdHi6B
        prefix:
          type: string
          readOnly: true
          description: Directory of the file (the `path` without its last segment). Read-only — set it via
            `prefix` on write.
          example: /images
        filename:
          type: string
          description: Original / download name and the key's leaf segment.
          example: logo.png
        path:
          type: string
          nullable: true
          readOnly: true
          description: Full key of the file within the project — `prefix` + `/` + `filename` (e.g.
            /images/logo.png). Read-only; unique per project; the file's identity and policy-SRN
            target.
          example: /images/logo.png
        content_type:
          type: string
          nullable: true
          description: MIME type of the file
          example: application/pdf
        size:
          type: integer
          nullable: true
          description: File size in bytes
          example: 1024
        metadata:
          $ref: "#/components/schemas/MetadataBag"
        tags:
          $ref: "#/components/schemas/TagBag"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    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`.
    MetadataBag:
      type: object
      description: >-
        Caller-owned annotations on a resource, stored as the object they were written as: the types
        a value was written with are the types a read returns, so a filter can ask an ordering
        question about a number. Unlike other body fields, keys are stored and returned verbatim in
        the casing supplied — they are not converted between snake_case and camelCase.


        No key is reserved, and that is the point: every piece of state the platform owns lives in
        its own typed column, so nothing written here reaches platform state. The platform never
        reads the bag — it is not an IAM context, not a policy input and not part of a prompt —
        which is what separates it from a tag bag.
      example:
        author: John
        revision: 2
    MetadataBagText:
      type: string
      description: A `MetadataBag` as JSON text. A multipart field carries text, so the object travels
        serialized on those surfaces and is parsed on arrival; a JSON body carries the object
        itself. Text that is not a JSON object is `400 VALIDATION_FAILED`.
      example: '{"author":"John","revision":2}'
    NullableMetadataBag:
      type: object
      nullable: true
      description: "A `MetadataBag` on a request field where `null` is meaningful: a full-replacement
        update that clears the bag. A record whose bag is unset leaves the field out."
      example:
        author: John
        revision: 2
    TagBag:
      type: object
      additionalProperties:
        type: string
      x-cli-flag-name: tags
      description: >-
        Key-value labels on a resource. A flat object of string values — an array, a nested object
        or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and
        stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB
        containment wherever tags are read: the `?tags=` filter, knowledge search, and the IAM
        `iam:ResourceTag/<key>` condition.


        Keys beginning `system.` are reserved: the platform writes them to record which
        conversation, actor, agent and role a row came from, and a write naming one is refused with
        `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.


        The bag is bounded, because every pair reaches the IAM context of every access check on the
        resource: at most 50 keys, each key at most 128 characters and each value at most 256. A
        write past a bound — including a merge that would grow the stored bag past the key count —
        is `400 VALIDATION_FAILED` with `meta.limit` naming the bound it crossed. `system.*` keys
        are the platform's and do not count against the 50.
      example:
        team: finance
        env: prod
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    TagsQuery:
      name: tags
      in: query
      required: false
      description: >
        Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain
        colons). Repeat the parameter for several pairs; **all** must be present with exactly that
        value.
      schema:
        type: array
        items:
          type: string
      style: form
      explode: true
      example:
        - env:prod
    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"
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: The credential is scoped to a different project, or the caller's role in the project
        does not carry this action.
      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"
