Kagura AI Files API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Files API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: Files
  description: 'Platform-managed file storage (Issue #485). Presigned upload to Cloudflare R2, per-workspace quota.'
paths:
  /api/v1/files/reserve:
    post:
      tags:
      - Files
      summary: Reserve Upload
      description: 'Reserve quota and return a presigned PUT URL for the upload.


        The client computes the sha256 ahead of time so the server can dedup

        against the active set on this workspace. Repeated calls with the

        same sha256 from the same workspace return 409; when the existing file

        is in the same context as the request and is ``uploaded``, the 409 body

        carries it as a top-level ``existing_file`` (``FileObjectOut``) so the

        SDK can use it instead of uploading again (#1693). An earlier upload

        that has not completed (``reserved``) is not handed out, and a

        duplicate in another context names no file (#1136).'
      operationId: reserve_upload_api_v1_files_reserve_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileReserveRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileReserveResponse'
        '409':
          description: The workspace already holds an active file with this sha256 (`RES-002`). When that file is in the same context as the request (both unbound counts as the same) and its upload has completed (`status` `uploaded`), the body also carries it as a top-level `existing_file` object; otherwise it is omitted.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/files/{file_id}/confirm:
    post:
      tags:
      - Files
      summary: Confirm Upload
      description: 'Verify the upload landed in R2 and finalize the row.


        Idempotent: confirming an already-uploaded file with a matching

        sha256 returns the existing row unchanged.'
      operationId: confirm_upload_api_v1_files__file_id__confirm_post
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: File Id
      - name: workspace_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Owning workspace
          title: Workspace Id
        description: Owning workspace
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileConfirmRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObjectOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/files/{file_id}/download-url:
    get:
      tags:
      - Files
      summary: Get Download Url
      description: Return a short-lived presigned GET URL.
      operationId: get_download_url_api_v1_files__file_id__download_url_get
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: File Id
      - name: workspace_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Owning workspace
          title: Workspace Id
        description: Owning workspace
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownloadUrlOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/files/{file_id}:
    delete:
      tags:
      - Files
      summary: Delete File
      description: 'Soft-delete the file and immediately release the quota.


        The R2 binary lingers for 7 days (sweeper handles deletion); the

        workspace counter is decremented in the same transaction (R5).'
      operationId: delete_file_api_v1_files__file_id__delete
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: File Id
      - name: workspace_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Owning workspace
          title: Workspace Id
        description: Owning workspace
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/files:
    get:
      tags:
      - Files
      summary: List Files
      description: List accessible files, optionally restricted to shared storage or one context.
      operationId: list_files_api_v1_files_get
      parameters:
      - name: workspace_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Owning workspace
          title: Workspace Id
        description: Owning workspace
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      - name: scope
        in: query
        required: false
        schema:
          enum:
          - all
          - workspace
          type: string
          description: Use workspace for shared files without a context
          default: all
          title: Scope
        description: Use workspace for shared files without a context
      - name: context_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Only files bound to this context; access checks still apply
          title: Context Id
        description: Only files bound to this context; access checks still apply
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileObjectOut'
                title: Response List Files Api V1 Files Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FileReserveResponse:
      properties:
        file_id:
          title: File Id
        upload_url:
          title: Upload Url
        expires_at:
          title: Expires At
      type: object
      required:
      - file_id
      - upload_url
      - expires_at
      title: FileReserveResponse
    FileDownloadUrlOut:
      properties:
        download_url:
          title: Download Url
      type: object
      required:
      - download_url
      title: FileDownloadUrlOut
    FileConfirmRequest:
      properties:
        sha256:
          type: string
          maxLength: 64
          minLength: 64
          pattern: ^[0-9a-fA-F]{64}$
          title: Sha256
      type: object
      required:
      - sha256
      title: FileConfirmRequest
      description: Body for ``POST /api/v1/files/{file_id}/confirm``.
    FileObjectOut:
      properties:
        id:
          title: Id
        workspace_id:
          title: Workspace Id
        context_id:
          title: Context Id
        filename:
          title: Filename
        content_type:
          title: Content Type
        size_bytes:
          title: Size Bytes
        sha256:
          title: Sha256
        status:
          title: Status
        created_at:
          title: Created At
        uploaded_at:
          title: Uploaded At
      type: object
      required:
      - id
      - workspace_id
      - filename
      - content_type
      - size_bytes
      - sha256
      - status
      - created_at
      title: FileObjectOut
      description: 'Subset of ``FileObject`` exposed to clients.


        ``from_attributes=True`` lets us pass the ORM row directly to

        ``model_validate`` — no per-field copy needed.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FileReserveRequest:
      properties:
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
        context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Context Id
          description: 'Optional owning context (Issue #1136). When set, the caller must have write access to it and the file inherits that context''s ACL for all later read/write/list access. Omit for a workspace-scoped file (legacy behaviour: any workspace viewer can download it).'
        filename:
          type: string
          maxLength: 512
          minLength: 1
          title: Filename
        content_type:
          type: string
          maxLength: 255
          minLength: 1
          title: Content Type
        size_bytes:
          type: integer
          exclusiveMinimum: 0.0
          title: Size Bytes
        sha256:
          type: string
          maxLength: 64
          minLength: 64
          pattern: ^[0-9a-fA-F]{64}$
          title: Sha256
          description: Hex sha256 of the bytes the client will PUT. Accepts upper- or lower-case; the service canonicalizes to lowercase before any storage / dedup / signing use.
      type: object
      required:
      - workspace_id
      - filename
      - content_type
      - size_bytes
      - sha256
      title: FileReserveRequest
      description: Body for ``POST /api/v1/files/reserve``.