Get contents at a specific repository path¶

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

This endpoint retrieves the file content or directory entry information at the specified repository path. It returns the file type, size, content encoding, and SHA, and provides the corresponding API URL, web page URL, and download URL. When the path points to a directory, it returns an array of the file entries in that directory.

Access token support¶

AtomGit user access tokens (AtomGit user access tokens)

Anonymous access¶

This endpoint allows 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
`ref`	query	string	No	Branch, tag, or commit; default: the repository's default branch (main)

Response parameters¶

Field	Type	Always returned	Nullable	Description
`type`	string	Yes	No	Content type, such as `file` or `dir`
`encoding`	string	Yes	No	Content encoding, such as `base64`
`size`	integer	Yes	No	File size (in bytes)
`name`	string	Yes	No	File name
`path`	string	Yes	No	File path
`content`	string	Yes	Yes	File content (may be `null`)
`sha`	string	Yes	No	File SHA
`url`	string	Yes	No	API URL of the content
`html_url`	string	Yes	No	Web page URL of the content
`download_url`	string	Yes	No	Download URL of the content
`_links`	object	Yes	No	Related link information

_links object

Field	Type	Always returned	Nullable	Description
`_links.self`	string	Yes	No	API URL of the content
`_links.html`	string	Yes	No	Web page URL of the content

Note: When path points to a directory, the response is an array of file entries, and each element has the same structure as the single file object above.

Error responses¶

The following are examples of error responses the endpoint may return; the error field names are subject to the actual backend response.

400 Invalid parameters

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

401 Unauthenticated

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

404 Content not found

{
  "error": "not_found",
  "message": "The repository or path does not exist"
}

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (Bad Request)
`401`	Authentication required (Requires authentication)
`403`	Forbidden
`404`	Not found (Not Found)
`500`	Internal system error (Internal Server Error)

Request example¶

Parameter notes¶

<owner> — Namespace address the repository belongs to (organization or personal path);
<repo> — Repository path (path);
<path> — File path of the content to retrieve;
<ref> — Branch, tag, or commit; when omitted, the repository's default branch (main) is used.

This endpoint allows anonymous access, so the examples can omit the access token. To include it, append ?access_token=<token>.

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>?ref=<ref>' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch("https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>?ref=<ref>", {
  headers: {
    "Accept": "application/json",
  },
});

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

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

Python¶

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/contents/<path>",
    params={"ref": "<ref>"},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "type": "file",
  "encoding": "base64",
  "size": 19,
  "name": "Note2.md",
  "path": "Note2.md",
  "content": "JXU2RDRCJXU4QkQ1d2ViaG9vaw==",
  "sha": "e5699fe1b360d6c799ee58b24fb5a670b1e14851",
  "url": "https://api.atomgit.com/api/v5/repos/daming_1/zhu_di/contents/Note2.md",
  "html_url": "https://api.atomgit.com/daming_1/zhu_di/blob/master/Note2.md",
  "download_url": "https://api.atomgit.com/daming_1/zhu_di/raw/master/Note2.md",
  "_links": {
    "self": "https://api.atomgit.com/api/v5/repos/daming_1/zhu_di/contents/Note2.md",
    "html": "https://api.atomgit.com/daming_1/zhu_di/blob/master/Note2.md"
  }
}

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`403`	Forbidden
`404`	The requested path or resource does not exist
`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