Skip to content

Create a new file

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

This endpoint creates a new file in the specified repository. The request must provide the base64-encoded file content and a commit message, and you can optionally specify the commit branch and committer information. On success, it returns the commit result, including the SHA, author, and committer information.

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 (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:

The request body is a JSON object: content (required) is the file content and must be base64-encoded; message (required) is the commit message; branch and author are optional.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "content": {
      "description": "File content; must be base64-encoded",
      "type": "string"
    },
    "message": {
      "description": "Commit message",
      "type": "string"
    },
    "branch": {
      "description": "Branch to commit to",
      "type": "string"
    },
    "author": {
      "description": "Committer information",
      "type": "object",
      "properties": {
        "name": {
          "description": "Author name; defaults to the current user's name",
          "type": "string"
        },
        "email": {
          "description": "Author email; defaults to the current user's email",
          "type": "string"
        }
      }
    }
  },
  "required": ["content", "message"]
}

Response parameters

Field Type Always returned Nullable Description
commit object Yes No Commit information

commit object

Field Type Always returned Nullable Description
commit.sha string Yes No Commit SHA
commit.author object Yes No Author information
commit.committer object Yes No Committer information
commit.message string Yes No Commit information
commit.parents object[] Yes No Parent commit list

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 Author 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

commit.parents[] object

Field Type Always returned Nullable Description
commit.parents[].sha string Yes No Parent commit SHA

Error responses

400 Invalid parameters

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

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)
400 Invalid parameters (Bad Request)
401 Authentication required (Requires authentication)
403 Forbidden
404 Resource not found (Not Found)
500 Internal system error (Internal Server Error)

Request example

Parameter notes

Replace <owner> with the namespace address the repository belongs to (enterprise, organization, or personal path); Replace <repo> with the repository path (path); Replace <path> with the file path to create (e.g. docs/README.md); Replace <token> with your AtomGit user access token.

cURL

curl -X POST 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "IyBBbGwgY29weXJpZ2h0IHJlc2VydmVk",
    "message": "create new file",
    "branch": "main",
    "author": {
      "name": "octocat",
      "email": "octocat@example.com"
    }
  }'

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: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: "IyBBbGwgY29weXJpZ2h0IHJlc2VydmVk",
      message: "create new file",
      branch: "main",
      author: { name: "octocat", email: "octocat@example.com" }
    })
  }
);

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

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

Python

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>",
    params={"access_token": "<token>"},
    json={
        "content": "IyBBbGwgY29weXJpZ2h0IHJlc2VydmVk",
        "message": "create new file",
        "branch": "main",
        "author": {"name": "octocat", "email": "octocat@example.com"}
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example

Status code: 200

{
  "commit": {
    "sha": "668cb104692b30d537b07f3721df9956d073d343",
    "author": {
      "name": "GitCode2023",
      "email": "13328943+gitcode_admin@user.noreply.gitcode.com",
      "date": "2024-04-11T09:15:20+00:00"
    },
    "committer": {
      "name": "Gitee",
      "email": "noreply@gitcode.com",
      "date": "2024-04-11T09:15:20+00:00"
    },
    "message": "22222",
    "parents": [
      {
        "sha": "0117aa5c6bc8e33d18ad8911afa3cbb54a1faabe"
      }
    ]
  }
}

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