---
title: "Update a file in a repository if SHA is set, or create the file if SHA is not set"
method: PUT
path: "/repos/{owner}/{repo}/contents/{filepath}"
tags: ["repository"]
---

# Update a file in a repository if SHA is set, or create the file if SHA is not set

`PUT /repos/{owner}/{repo}/contents/{filepath}`

## Request

- Base URL: `https://demo.gitea.com/api/v1`
- URL: `https://demo.gitea.com/api/v1/repos/{owner}/{repo}/contents/{filepath}`
- Auth: one of:
  - HTTP basic
  - API key in query parameter `token`
  - API key in query parameter `access_token`
  - API key in header `Authorization`
  - API key in query parameter `sudo`
  - API key in header `Sudo`
  - API key in header `X-GITEA-OTP`
- TypeScript: <https://skmtc.dev/gitea/apis/gitea-api/docs/repos/:owner/:repo/contents/:filepath/put.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `owner` string, required
- `repo` string, required
- `filepath` string, required

## Request body

- UpdateFileOptions: UpdateFileOptions options for updating or creating a file Note: `author` and `committer` are optional (if only one is given, it will be used for the other, otherwise the authenticated user will be used)
  - `author` Identity: Identity for a person's identity like an author or committer
    - `email` string, email: Email is the person's email address
    - `name` string: Name is the person's name
  - `branch` string: branch (optional) is the base branch for the changes. If not supplied, the default branch is used
  - `committer` Identity: Identity for a person's identity like an author or committer
    - `email` string, email: Email is the person's email address
    - `name` string: Name is the person's name
  - `content` string, required: content must be base64 encoded
  - `dates` CommitDateOptions: CommitDateOptions store dates for GIT_AUTHOR_DATE and GIT_COMMITTER_DATE
    - `author` string, date-time: Author is the author date for the commit
    - `committer` string, date-time: Committer is the committer date for the commit
  - `force_push` boolean: force_push (optional) will do a force-push if the new branch already exists
  - `from_path` string: from_path (optional) is the path of the original file which will be moved/renamed to the path in the URL
  - `message` string: message (optional) is the commit message of the changes. If not supplied, a default message will be used
  - `new_branch` string: new_branch (optional) will make a new branch from base branch for the changes. If not supplied, the changes will be committed to the base branch
  - `sha` string: the blob ID (SHA) for the file that already exists to update, or leave it empty to create a new file
  - `signoff` boolean: Add a Signed-off-by trailer by the committer at the end of the commit log message.

## Response `200`

FileResponse

- FileResponse: FileResponse contains information about a repo's file
  - `commit` FileCommitResponse
    - `author` CommitUser
      - `date` string: Date is the commit date in string format
      - `email` string, email: Email is the person's email address
      - `name` string: Name is the person's name
    - `committer` CommitUser
      - `date` string: Date is the commit date in string format
      - `email` string, email: Email is the person's email address
      - `name` string: Name is the person's name
    - `created` string, date-time: Created is the time when the commit was created
    - `html_url` string: HTMLURL is the web URL for viewing this commit
    - `message` string: Message is the commit message
    - `parents` CommitMeta[]: Parents contains parent commit metadata
      - `created` string, date-time: Created is the time when the commit was created
      - `sha` string: SHA is the commit SHA hash
      - `url` string: URL is the API URL for the commit
    - `sha` string: SHA is the commit SHA hash
    - `tree` CommitMeta
      - `created` string, date-time: Created is the time when the commit was created
      - `sha` string: SHA is the commit SHA hash
      - `url` string: URL is the API URL for the commit
    - `url` string: URL is the API URL for the commit
  - `content` ContentsResponse: ContentsResponse contains information about a repo's entry's (dir, file, symlink, submodule) metadata and content
    - `_links` FileLinksResponse: FileLinksResponse contains the links for a repo's file
      - `git` string: GitURL is the Git API URL for this file
      - `html` string: HTMLURL is the web URL for this file
      - `self` string: Self is the API URL for this file
    - `content` string: `content` is populated when `type` is `file`, otherwise null
    - `download_url` string: DownloadURL is the direct download URL for this file
    - `encoding` string: `encoding` is populated when `type` is `file`, otherwise null
    - `git_url` string: GitURL is the Git API URL for this blob or tree
    - `html_url` string: HTMLURL is the web URL for this file or directory
    - `last_author_date` string, date-time
    - `last_commit_message` string: LastCommitMessage is the message of the last commit that affected this file
    - `last_commit_sha` string: LastCommitSHA is the SHA of the last commit that affected this file
    - `last_committer_date` string, date-time
    - `lfs_oid` string: LfsOid is the Git LFS object ID if this file is stored in LFS
    - `lfs_size` integer: LfsSize is the file size if this file is stored in LFS
    - `mode` string: `mode` is the Git file mode as an octal string, e.g. `100644` (regular), `100755` (executable), `120000` (symlink), `160000` (submodule)
    - `name` string: Name is the file or directory name
    - `path` string: Path is the full path to the file or directory
    - `sha` string: SHA is the Git blob or tree SHA
    - `size` integer: Size is the file size in bytes
    - `submodule_git_url` string: `submodule_git_url` is populated when `type` is `submodule`, otherwise null
    - `target` string: `target` is populated when `type` is `symlink`, otherwise null
    - `type` string: `type` will be `file`, `dir`, `symlink`, or `submodule`
    - `url` string: URL is the API URL for this file or directory
  - `verification` PayloadCommitVerification: PayloadCommitVerification represents the GPG verification of a commit
    - `payload` string: The signed payload content
    - `reason` string: The reason for the verification status
    - `signature` string: The GPG signature of the commit
    - `signer` PayloadUser: PayloadUser represents the author or committer of a commit
      - `email` string, email
      - `name` string: Full name of the commit author
      - `username` string: username of the user
    - `verified` boolean: Whether the commit signature is verified

## Other responses

- `201`: FileResponse
- `default`: APIError is error format response

## Changes

- **2026-10-28** `7ef50c4c527f`: 4 info
  - removed the non-success response with the status `403`
  - removed the non-success response with the status `404`
  - removed the non-success response with the status `422`
  - removed the non-success response with the status `423`
- **2026-07-13** `4df6be504c96`: 1 info
  - added the success response with the status `201`

[Operation history](https://skmtc.dev/gitea/apis/gitea-api/changes/repos/:owner/:repo/contents/:filepath/put.md)

---

[API](https://skmtc.dev/gitea/apis/gitea-api.md) - [All operations](https://skmtc.dev/gitea/apis/gitea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitea/apis/gitea-api/revisions/7ef50c4c527f?raw)