Delete a file¶

DELETE /api/v5/repos/{owner}/{repo}/contents/{path}

This endpoint deletes a file on the specified branch in the repository. You identify the target file by specifying its file path and Blob SHA. The delete operation automatically generates the corresponding commit record and returns the commit information for this delete operation.

Access token support¶

AtomGit user access tokens (AtomGit user access tokens)

Anonymous access¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Namespace address the repository belongs to (enterprise, organization, or personal path)
`repo`	path	string	Yes	Repository path (path)
`path`	path	string	Yes	File path
`access_token`	query	string	Yes	User authorization code

Request Body:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sha": {
      "description": "Blob SHA of the file",
      "type": "string"
    },
    "message": {
      "description": "Commit information",
      "type": "string"
    },
    "branch": {
      "description": "Branch name. Defaults to the repository's default branch",
      "type": "string"
    }
  },
  "required": ["sha", "message"]
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`commit`	object	Yes	No	Commit information
`content`	object	No	Yes	File information (the delete operation usually returns `null`)

commit object

Field	Type	Always returned	Nullable	Description
`commit.sha`	string	Yes	No	commit ID
`commit.author`	object	Yes	No	Author information
`commit.committer`	object	Yes	No	Committer information
`commit.message`	string	Yes	No	Commit information
`commit.tree`	string	Yes	No	tree ID
`commit.parents`	string[]	Yes	Yes	Parent nodes (list of parent commit IDs)

`commit.author` object¶

Field	Type	Always returned	Nullable	Description
`commit.author.name`	string	Yes	No	Author name
`commit.author.email`	string	Yes	No	Author email
`commit.author.date`	string	Yes	No	Commit time

`commit.committer` object¶

Field	Type	Always returned	Nullable	Description
`commit.committer.name`	string	Yes	No	Committer name
`commit.committer.email`	string	Yes	No	Committer email
`commit.committer.date`	string	Yes	No	Commit time

`content` object¶

Field	Type	Always returned	Nullable	Description
`content.name`	string	Yes	No	Name
`content.path`	string	Yes	No	Path
`content.size`	integer	Yes	Yes	Size
`content.sha`	string	Yes	No	blob ID
`content.type`	string	Yes	No	Type (`file`)

Error responses¶

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "The sha parameter cannot be empty",
  "field": "sha"
}

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

Note: The error field names are subject to the actual backend response.

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`304`	Not modified
`401`	Authentication required (Requires authentication)
`403`	Forbidden

Request example¶

Parameter notes¶

The examples use the following placeholders:

<owner> — Namespace address the repository belongs to (enterprise, organization, or personal path); <repo> — Repository path (path); <path> — File path to delete (nested directories are supported, e.g. docs/readme.md); <token> — Your AtomGit user access token; <file_blob_sha> — Blob SHA of the file's current version.

cURL¶

curl -X DELETE 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sha": "<file_blob_sha>",
    "message": "Delete file",
    "branch": "master"
  }'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>?access_token=<token>",
  {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sha: "<file_blob_sha>",
      message: "Delete file",
      branch: "master",
    }),
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.delete(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>",
    params={"access_token": "<token>"},
    json={
        "sha": "<file_blob_sha>",
        "message": "Delete file",
        "branch": "master",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "commit": {
    "sha": "2a90c33ede2c1eafc5943727fd57129d870ad2e4",
    "author": {
      "name": "xiaogang",
      "email": "1150456356@qq.com",
      "date": "2024-11-25T02:11:56.000Z"
    },
    "committer": {
      "name": "xiaogang",
      "email": "1150456356@qq.com",
      "date": "2024-11-25T02:11:56.000Z"
    },
    "message": "api delete file",
    "tree": "791f24a0da8c8458e40da3243bde183d59773514",
    "parents": [
      "33e9ee7ccd32835a0fb9f2af99264931c06fbe11"
    ]
  }
}

Error codes¶

Error code	Description
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`400`	Invalid parameters or the request cannot be parsed
`404`	The requested path does not exist
`405`	Request method not supported
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc