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

# Upload file

> Creates or updates a file in a workspace.

**Requirements:**
- The `ref_id` must be a workspace ID
- Requires a client ID header

**File content options:**
- Inline as binary data
- Via storage hints (storage_backend, storage_uri, sha1, size)

**Parameters:**
- `mode` - specifies file permissions
- `mtime` - sets the modification time

**Validation:**
Reserved paths containing '.diversion' are rejected.

**Returns:**
- `202 Accepted` on success
- `204 No Content` if no change was made




## OpenAPI

````yaml post /repos/{repo_id}/files/{ref_id}/{path}
openapi: 3.0.3
info:
  title: Diversion Core API
  description: >-
    Definition of the Core API used to access low-level functionality of
    Diversion
  version: 0.2.0
servers:
  - url: https://api.diversion.dev/v0
    description: Base endpoint
security: []
paths:
  /repos/{repo_id}/files/{ref_id}/{path}:
    parameters:
      - $ref: '#/components/parameters/RepoParam'
      - $ref: '#/components/parameters/RefParam'
      - $ref: '#/components/parameters/PathParam'
    post:
      tags:
        - File Mutation
      summary: Upload file to a new or existing path
      operationId: src.handlersv2.files.create_or_update_file
      parameters:
        - $ref: '#/components/parameters/ClientIDParam'
        - $ref: '#/components/parameters/StorageBackendParam'
        - $ref: '#/components/parameters/StorageUriParam'
        - $ref: '#/components/parameters/ModeParam'
        - $ref: '#/components/parameters/MtimeParam'
        - $ref: '#/components/parameters/SizeParam'
        - $ref: '#/components/parameters/SHA1Param'
      requestBody:
        required: false
        description: >-
          Blob binary contents, if the file is a blob and if alternative storage
          solution was not used.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '202':
          description: File created or updated
        '400':
          description: Path should be normalized
        '412':
          description: Race condition, please attempt the operation again
        default:
          $ref: '#/components/responses/Error'
      security:
        - OAuth2:
            - coreapi/write
components:
  parameters:
    RepoParam:
      in: path
      name: repo_id
      required: true
      schema:
        type: string
        example: example_id
        minLength: 3
        maxLength: 128
      description: >-
        The repo ID of the repository. Repo _name_ can be used instead of the
        ID, but usage of ID for permanent linking and API requests is preferred.
    RefParam:
      in: path
      name: ref_id
      schema:
        type: string
        example: example_id
        minLength: 3
        maxLength: 128
      required: true
      description: An ID of a workspace, branch or commit.
    PathParam:
      in: path
      name: path
      schema:
        type: string
        format: path
        example: /path/to/file
      required: true
      description: A path to a file inside the repository.
    ClientIDParam:
      in: header
      name: X-DV-Client-ID
      description: The unique id of the client making this request
      required: true
      schema:
        type: string
    StorageBackendParam:
      in: query
      name: storage_backend
      description: An optional storage type for async upload.
      schema:
        $ref: '#/components/schemas/StorageBackend'
    StorageUriParam:
      in: query
      name: storage_uri
      description: An optional storage uri to be sent along storage_backend.
      schema:
        $ref: '#/components/schemas/StorageUri'
    ModeParam:
      in: query
      name: mode
      description: The file mode (as Unix mode)
      required: true
      schema:
        $ref: '#/components/schemas/FileMode'
    MtimeParam:
      in: query
      name: mtime
      description: The file's modification time in seconds since epoch
      required: true
      schema:
        type: integer
        format: int64
    SizeParam:
      in: query
      name: size
      description: Blob size in bytes
      schema:
        type: integer
        format: int64
    SHA1Param:
      in: query
      name: sha1
      description: A sha1 hexdigest
      example: 7d76d48d64d7ac5411d714a4bb83f37e3e5b8df6
      schema:
        type: string
  responses:
    Error:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StorageBackend:
      type: integer
      enum:
        - 1
        - 2
      description: 'One of: 1 - EFS, 2 - S3'
      x-ogen-enum-naming:
        '1': StorageBackend_EFS
        '2': StorageBackend_S3
    StorageUri:
      type: string
      description: Coupled with storage_backend, a uri to storage location
      example: repo_id/2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
    FileMode:
      type: integer
      description: The file mode (as Unix mode)
      enum:
        - 16877
        - 33188
        - 33261
        - 40960
      x-ogen-enum-naming:
        '16877': FileMode_TREE
        '33188': FileMode_FILE
        '33261': FileMode_EXECUTABLE
        '40960': FileMode_SYMLINK
    Error:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 403
        detail:
          type: string
          example: User not authorized to perform the requested action on the resource
        title:
          type: string
        type:
          type: string
      required:
        - status
        - detail
  securitySchemes:
    OAuth2:
      type: oauth2
      x-tokenInfoFunc: src.token_info.token_auth
      description: This API uses OAuth 2 with the implicit grant flow
      flows:
        implicit:
          authorizationUrl: https://auth.diversion.dev/oauth2/authorize
          scopes:
            coreapi/read: Operations with no possible side-effects
            coreapi/write: Modifying operations
            coreapi/admin: >-
              Organizational operations like adding a repo or changing repo
              properties

````