openapi: 3.0.0
info:
  title: Private IPFS API
  version: 1.0.0
servers:
  - url: https://uploads.pinata.cloud/v3
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []
paths:
  /files:
    post:
      tags:
        - default
      summary: Upload a File
      description: |
        `org:files:write`
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - network
              properties:
                network:
                  type: string
                  enum:
                    - public
                    - private
                  description: Determine if the file should be uploaded to either the public or private IPFS network. If not designated it will default to private.
                  default: private
                file:
                  type: string
                  format: binary
                  description: File object you want to upload
                name:
                  type: string
                  description: Add a custom name for the file
                group_id:
                  type: string
                  description: ID of the group you would like to upload
                keyvalues:
                  type: object
                  description: Add additional key value metadata to files upon upload
                  additionalProperties:
                    type: string
                car:
                  type: boolean
                  description: Upload a file as a raw CAR file (only supported for public network)
                cid_version:
                  type: string
                  enum:
                    - v0
                    - v1
                    - unixfs-v1-2025
                  default: v1
                  description: |
                    UnixFS import profile used to hash the upload. `v1` (default) produces a CIDv1 (`bafy…`) with raw leaves, 256 KiB chunks and up to 174 links per node, matching `ipfs add --cid-version=1`. `v0` produces a legacy CIDv0 (`Qm…`) with dag-pb leaves, matching `ipfs add --cid-version=0`. `unixfs-v1-2025` produces a CIDv1 using the [IPIP-499](https://github.com/ipfs/specs/pull/499) profile — 1 MiB chunks and up to 1024 links per node — matching kubo's `test-cid-v1-wide` config profile. The profile is fixed when the upload is created and cannot be changed while resuming it.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      cid:
                        type: string
                      created_at:
                        type: string
                      size:
                        type: number
                      number_of_files:
                        type: number
                      mime_type:
                        type: string
                      user_id:
                        type: string
                      group_id:
                        type: string
                      is_duplicate:
                        type: boolean
  /files/sign:
    post:
      tags:
        - default
      summary: Create Signed Upload URL
      description: |
        `org:files:write`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - date
                - expires
              properties:
                date:
                  type: number
                  description: The unix timestamp that the URL is signed, ie time of request
                expires:
                  type: number
                  description: How long the URL is valid for in sconds after signing based on the date parameter
                max_file_size:
                  type: number
                  description: Restrict the max size of a file upload in `bytes`
                allow_mime_types:
                  type: array
                  description: Array of allowed mime types for a file upload, includes wildcards `"image/*"`
                  items:
                    type: string
                group_id:
                  type: string
                  description: ID of the group that the file will be uploaded to
                keyvalues:
                  type: object
                  description: Add additional key value metadata to files upon upload
                  additionalProperties:
                    type: string
                filename:
                  type: string
                  description: Name of the file that will be uploaded
                cid_version:
                  type: string
                  enum:
                    - v0
                    - v1
                    - unixfs-v1-2025
                  default: v1
                  description: UnixFS import profile used to hash the upload made with this URL. See the `cid_version` option on `POST /files`.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
  /vectorize/files/{file_id}:
    post:
      tags:
        - Private Files
      summary: Vectorize a File
      description: |
        `org:write`
      parameters:
        - schema:
            type: string
            format: uuid
          required: true
          name: file_id
          in: path
      responses:
        "200":
          description: Vectorize File Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                  - success
    delete:
      tags:
        - Private Files
      summary: Delete File Vectors
      description: |
        `org:write`
      parameters:
        - schema:
            type: string
            format: uuid
          required: true
          name: file_id
          in: path
      responses:
        "200":
          description: Vectorize File Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                  - success
  /vectorize/groups/{group_id}/query:
    post:
      tags:
        - Private Files
      summary: Query File Vectors
      description: |
        `org:write`
      parameters:
        - schema:
            type: string
            description: ID of the target group
            format: uuid
          required: true
          name: group_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Query string
      responses:
        "200":
          description: Vectorize File Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: number
                      matches:
                        type: array
                        items:
                          type: object
                          properties:
                            file_id:
                              type: string
                            cid:
                              type: string
                            score:
                              type: number