File change information submitted by a PR¶

GET /api/v5/repos/{owner}/{repo}/pulls/{number}/files.json

This endpoint queries the file change information submitted by the specified PR. It returns the number of file changes, the numbers of added and removed lines, the commit information of the comparison references, and the specific diff content of each file, including file paths and line-level additions and deletions.

Access token support¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint allows anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	The namespace address the repository belongs to (the address path of an organization or individual)
`repo`	path	string	Yes	Repository path (path)
`number`	path	integer	Yes	The number of the PR, that is, the ordinal number of the PR in this repository

Response parameters¶

Field	Type	Always returned	Nullable	Description
`code`	integer	—	—	Response status code; `0` indicates success
`added_lines`	integer	—	—	Number of added lines
`remove_lines`	integer	—	—	Number of removed lines
`count`	integer	—	—	Number of file changes
`diff_refs`	object	—	—	Commit information of the comparison references
`diffs`	array	—	—	List of file changes

`diff_refs` object¶

Field	Type	Always returned	Nullable	Description
`diff_refs.base_sha`	string	—	—	SHA of the base commit for comparison
`diff_refs.start_sha`	string	—	—	SHA of the start commit
`diff_refs.head_sha`	string	—	—	SHA of the latest commit

`diffs` array element object¶

Field	Type	Always returned	Nullable	Description
`diffs.new_blob_id`	string	—	—	ID of the new file blob
`diffs.statistic`	object	—	—	File statistics
`diffs.head`	object	—	—	Commit information for the file
`diffs.added_lines`	integer	—	—	Number of lines added in this file
`diffs.remove_lines`	integer	—	—	Number of lines removed in this file
`diffs.content`	object	—	—	File content diff

`diffs.statistic` object¶

Field	Type	Always returned	Nullable	Description
`diffs.statistic.type`	string	—	—	File type (example value `text_type`)
`diffs.statistic.path`	string	—	—	File path
`diffs.statistic.old_path`	string	—	—	Original file path
`diffs.statistic.new_path`	string	—	—	New file path
`diffs.statistic.view`	integer	—	—	View identifier

`diffs.head` object¶

Field	Type	Always returned	Nullable	Description
`diffs.head.url`	string	—	—	File content URL
`diffs.head.commit_id`	string	—	—	commit id

`diffs.content` object¶

Field	Type	Always returned	Nullable	Description
`diffs.content.text`	array	—	—	List of diff line texts

`diffs.content.text` array element object¶

Field	Type	Always returned	Nullable	Description
`diffs.content.text.line_content`	string	—	—	Line content
`diffs.content.text.old_line`	object	—	—	Old line information
`diffs.content.text.new_line`	object	—	—	New line information
`diffs.content.text.type`	string	—	—	Line type (`old` / `new`)

`diffs.content.text.old_line` object¶

Field	Type	Always returned	Nullable	Description
`diffs.content.text.old_line.line_code`	string	—	—	Line number code of the old line
`diffs.content.text.old_line.line_num`	string	—	—	Line number of the old line; `""` when there is no corresponding line

`diffs.content.text.new_line` object¶

Field	Type	Always returned	Nullable	Description
`diffs.content.text.new_line.line_code`	string	—	—	Line number code of the new line
`diffs.content.text.new_line.line_num`	string	—	—	Line number of the new line; `""` when there is no corresponding line

Error responses¶

A 200/success response alone is not enough: callers need to know what a failure looks like in order to write error handling.

400 Invalid parameters

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

401 Unauthenticated

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

404 Resource not found

{
  "error": "not_found",
  "message": "The PR does not exist"
}

The error field names are subject to what the backend actually returns.

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`304`	Not modified
`400`	Invalid parameters (Bad request)
`401`	Requires authentication
`403`	Forbidden
`404`	Not found
`405`	Request method not allowed
`429`	Too many requests, rate limit triggered
`500`	Internal server error

Request example¶

Parameter description¶

The example must be consistent with the rest of this document, so that it can be copied as-is and the call succeeds. This endpoint allows anonymous access, so the request example does not carry a token; if authentication is required, you can also pass your AtomGit user access token by appending ?access_token=<token> to the URL.

Replace <owner> with the namespace address the repository belongs to (the address path of an organization or individual); replace <repo> with the repository path (path); replace <number> with the number of the PR, that is, the ordinal number of the PR in this repository.

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls/<number>/files.json' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch("https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls/<number>/files.json", {
  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>/pulls/<number>/files.json",
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "code": 0,
  "added_lines": 7,
  "remove_lines": 7,
  "count": 2,
  "diff_refs": {
    "base_sha": "db015522f67b15e868c5f929ff1af4cba9ddd112",
    "start_sha": "db015522f67b15e868c5f929ff1af4cba9ddd112",
    "head_sha": "93cd8303ac07886610d738baf7ddd620f04ee778"
  },
  "diffs": [
    {
      "new_blob_id": "b575bd06b44029dc12771503388d61ea383169cb",
      "statistic": {
        "type": "text_type",
        "path": "1",
        "old_path": "1",
        "new_path": "1",
        "view": 0
      },
      "head": {
        "url": "https://api.atomgit.com/xiaogang/test/raw/93cd8303ac07886610d738baf7ddd620f04ee778/1",
        "commit_id": "93cd8303ac07886610d738baf7ddd620f04ee778"
      },
      "added_lines": 3,
      "remove_lines": 3,
      "content": {
        "text": [
          {
            "line_content": "111",
            "old_line": {
              "line_code": "356a192b7913b04c54574d18c28d46e6395428ab_1_1",
              "line_num": "1"
            },
            "new_line": {
              "line_code": "356a192b7913b04c54574d18c28d46e6395428ab_1_1",
              "line_num": ""
            },
            "type": "old"
          },
          {
            "line_content": "111222",
            "old_line": {
              "line_code": "356a192b7913b04c54574d18c28d46e6395428ab_2_1",
              "line_num": ""
            },
            "new_line": {
              "line_code": "356a192b7913b04c54574d18c28d46e6395428ab_2_1",
              "line_num": "1"
            },
            "type": "new"
          }
        ]
      }
    }
  ]
}

Error codes¶

Error code	Description
`400`	Invalid parameters or unparseable request
`401`	Unauthenticated or invalid credentials (missing/invalid access credentials)
`404`	Request path not found
`405`	Request method not supported
`429`	Too many requests, rate limit triggered
`500`	Internal server error

OpenAPI¶

{"paths": {"/api/v5/repos/{owner}/{repo}/pulls/{number}/files.json": {"get": {"tags": ["pull_requests"], "summary": "File change information submitted by a PR", "responses": {"200": {"content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"type": "integer", "description": "Response status code; 0 indicates success"}, "count": {"type": "integer", "description": "Number of file changes"}, "diffs": {"type": "array", "items": {"type": "object", "properties": {"head": {"type": "object", "properties": {"url": {"type": "string", "description": "File content URL"}, "commit_id": {"type": "string", "description": "commit id"}}}, "content": {"type": "object", "properties": {"text": {"type": "array", "items": {"type": "object", "properties": {"type": {"type": "string", "description": "Line type"}, "new_line": {"type": "object", "properties": {"line_num": {"type": "string", "description": "Line number of the new line"}, "line_code": {"type": "string", "description": "Line number code of the new line"}}}, "old_line": {"type": "object", "properties": {"line_num": {"type": "string", "description": "Line number of the old line"}, "line_code": {"type": "string", "description": "Line number code of the old line"}}}, "line_content": {"type": "string", "description": "Line content"}}}}}}, "statistic": {"type": "object", "properties": {"path": {"type": "string", "description": "File path"}, "type": {"type": "string", "description": "File type"}, "view": {"type": "integer", "description": "View identifier"}, "new_path": {"type": "string", "description": "New file path"}, "old_path": {"type": "string", "description": "Original file path"}}}, "added_lines": {"type": "integer", "description": "Number of lines added in this file"}, "new_blob_id": {"type": "string", "description": "ID of the new file blob"}, "remove_lines": {"type": "integer", "description": "Number of lines removed in this file"}}}}, "diff_refs": {"type": "object", "properties": {"base_sha": {"type": "string", "description": "SHA of the base commit for comparison"}, "head_sha": {"type": "string", "description": "SHA of the latest commit"}, "start_sha": {"type": "string", "description": "SHA of the start commit"}}}, "added_lines": {"type": "integer", "description": "Number of added lines"}, "remove_lines": {"type": "integer", "description": "Number of removed lines"}}}}, "description": "Success"}}, "parameters": [{"in": "path", "name": "owner", "schema": {"type": "string"}, "required": true, "description": "The namespace address the repository belongs to (the address path of an organization or individual)"}, {"in": "path", "name": "repo", "schema": {"type": "string"}, "required": true, "description": "Repository path (path)"}, {"in": "path", "name": "number", "schema": {"type": "integer"}, "required": true, "description": "The number of the PR, that is, the ordinal number of the PR in this repository"}], "description": "Call this endpoint to query the file change information submitted by a PR."}}}}

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