> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudsquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File by Path

> Upload a file to a path inside the project filesystem. Parent folders are created automatically.

<Note>
  **Conflict handling:** If a file already exists at the target path, the request fails with `409 Conflict`. Delete the existing file first if you need to overwrite it.
</Note>

## What this does

Uploads a file to the project filesystem at the specified `path` query parameter. Missing intermediate folders are created automatically (like `mkdir -p`). The request body uses the same `Document` schema as table file uploads.

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT \
    "https://api.cloudsquid.io/api/projects/my-project/files?path=/invoices/2024/jan.pdf" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "file": "'$(base64 -i jan.pdf)'",
      "filename": "jan.pdf",
      "mimetype": "application/pdf",
      "file_type": "binary"
    }'
  ```

  ```python Python theme={null}
  import requests, base64

  with open("jan.pdf", "rb") as f:
      encoded = base64.b64encode(f.read()).decode()

  response = requests.put(
      "https://api.cloudsquid.io/api/projects/my-project/files",
      params={"path": "/invoices/2024/jan.pdf"},
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={
          "file": encoded,
          "filename": "jan.pdf",
          "mimetype": "application/pdf",
          "file_type": "binary"
      }
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.cloudsquid.io/api/projects/my-project/files?path=/invoices/2024/jan.pdf",
    {
      method: "PUT",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        file: btoa(fileContent),
        filename: "jan.pdf",
        mimetype: "application/pdf",
        file_type: "binary"
      })
    }
  );
  ```
</CodeGroup>

Response (`201 Created`):

```json theme={null}
{
  "ftype": "file",
  "name": "jan.pdf",
  "size": 48210,
  "mimetype": "application/pdf",
  "modified_at": "2026-06-01T12:00:00Z",
  "url": "https://storage.googleapis.com/presigned?..."
}
```


## OpenAPI

````yaml put /projects/{project_name}/files
openapi: 3.0.3
info:
  title: Cloudsquid
  description: This is the backend of cloudsquid specification
  termsOfService: cloudsquid.io
  contact:
    email: info@cloudsquid.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.11
servers:
  - url: https://api.cloudsquid.io/api
    description: API
security:
  - api-key: []
paths:
  /projects/{project_name}/files:
    parameters:
      - name: project_name
        in: path
        required: true
        description: The name of the project
        schema:
          type: string
    put:
      tags:
        - filesystem
      summary: Upload a file to a path
      description: >
        Upload a file to the project filesystem at the given path. Missing
        parent folders

        are created automatically. Fails with 409 if a file already exists at
        the path.
      parameters:
        - name: path
          in: query
          required: true
          description: >-
            Absolute path inside the project (leading slash optional, no `..`
            segments)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Document'
      responses:
        '201':
          description: File uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad or malformed request (invalid path, missing body)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A file already exists at this path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Something unexpected happened
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Document:
      type: object
      properties:
        mimetype:
          description: the mimetype of the document being uploaded
          type: string
          enum:
            - application/pdf
            - application/json
            - image/jpg
            - image/jpeg
            - image/png
            - text/csv
            - text/plain
            - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
            - application/vnd.ms-excel
            - video/mp4
            - audio/mp3
            - audio/wav
            - audio/ogg
            - multipart/related
            - message/rfc822
        filename:
          description: the name of the file being uploaded
          type: string
        file_type:
          description: >-
            Indicates whether the file is a binary upload or a signed link to
            the document.
          type: string
          enum:
            - uri
            - binary
            - multipart
        file:
          oneOf:
            - type: string
              format: uri
              description: A signed URL to the file.
            - type: string
              description: A base64 encoded string of the file.
            - type: array
              description: A multipart file upload.
              items:
                type: object
                properties:
                  text:
                    type: string
                    description: The text content of the file.
                  file:
                    type: object
                    properties:
                      mimetype:
                        type: string
                        description: The MIME type of the file.
                      file_type:
                        description: >-
                          Indicates whether the file is a binary upload or a
                          signed link to the document.
                        type: string
                        enum:
                          - uri
                          - binary
                      content:
                        oneOf:
                          - type: string
                            description: The base64 encoded content of the file.
                          - type: string
                            format: uri
                            description: A signed URL to the file.
                    required:
                      - mimetype
                      - file_type
                      - content
      required:
        - file
        - mimetype
        - filename
        - file_type
    File:
      type: object
      description: A file object inside the filesystem
      properties:
        ftype:
          $ref: '#/components/schemas/FType'
        name:
          type: string
        size:
          type: integer
          description: size in bytes
        mimetype:
          type: string
        modified_at:
          type: string
          format: date-time
        url:
          type: string
          format: uri
          description: Presigned download url. 15min TTL.
      required:
        - name
        - ftype
    Error:
      type: object
      properties:
        errorMessage:
          type: string
      required:
        - errorMessage
    FType:
      type: string
      enum:
        - file
        - folder
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: X-API-Key

````