pinata-api-v3-uploads.yaml

openapi: 3.0.0
info:
  title: Private Files 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
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                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
      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
      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
                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
      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: Vectorize an existing file. File must already be part of a group.
      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: Delete file vectors for an existing file.
      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: Query file vectors for a given group
      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