Get the project pull request list
GET /api/v5/repos/{owner}/{repo}/pulls
This endpoint retrieves the pull request list of the specified repository. You can filter by state, target branch, time range, sorting, and pagination, and you can also return only the merge request counts for each state.
Access token support
- AtomGit user access tokens (AtomGit user access tokens)
Whether anonymous access is allowed
This endpoint allows anonymous access.
Request parameters
Response parameters
The response is an array of pull request objects; when only_count=true, the response is a merge request count object (see "only_count=true count response"). In the "Nullable" column of the table below, — means the reference documentation does not provide this information.
labels object
user object
head object
head.user object
head.repo object
head.repo.owner object
head.repo.assigner object
base object
base.user object
base.repo object
base.repo.owner object
base.repo.assigner object
diff_refs object
closed_by object
merged_by object
only_count=true count response
When only_count=true, the response is not an array of pull requests but the merge request counts for each state:
{
"all": 1,
"opened": 1,
"closed": 0,
"merged": 0,
"locked": 0
}
Error responses
This endpoint allows anonymous access; if the access token provided is invalid or has expired, 401 is returned. The error response field names are subject to what the backend actually returns.
400 Bad request
{
"error": "invalid_request",
"message": "Invalid value for the state parameter",
"field": "state"
}
401 Unauthenticated
{
"error": "unauthorized",
"message": "Missing or invalid access token"
}
HTTP response status codes
Request example
Parameter descriptions
The placeholders in the examples mean the following:
<owner> is replaced with the namespace address the repository belongs to (the address path of an enterprise, organization, or personal namespace);
<repo> is replaced with the repository path (path).
This endpoint allows anonymous access, so the examples do not carry authentication information; to access as a signed-in user, you can include an AtomGit user access token.
cURL
curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/pulls?state=all&per_page=20' \
-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?state=all&per_page=20",
{
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",
params={"state": "all", "per_page": 20},
headers={"Accept": "application/json"},
timeout=10,
)
resp.raise_for_status()
print(resp.json())
Response example
Status code: 200
[
{
"number": 1,
"html_url": "https://api.atomgit.com/owner/repo/pulls/1",
"url": "https://api.atomgit.com/api/v5/repos/owner/repo/pulls/1",
"close_related_issue": 0,
"prune_branch": true,
"draft": false,
"labels": [
{
"id": 100,
"name": "bug",
"color": "#ee0701",
"created_at": "2024-11-20T13:00:21+08:00",
"updated_at": "2024-11-20T13:00:21+08:00"
}
],
"user": {
"id": "1",
"user_id": "1001",
"object_id": "u_1001",
"login": "octocat",
"name": "octocat",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "octocat@example.com",
"name_cn": "Example User",
"html_url": "https://api.atomgit.com/octocat"
},
"assignees": ["octocat"],
"testers": [],
"head": {
"label": "octocat:feature",
"ref": "feature",
"sha": "abc123def456",
"user": {
"id": "1",
"login": "octocat",
"name": "octocat",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "octocat@example.com",
"name_cn": "Example User",
"html_url": "https://api.atomgit.com/octocat"
},
"repo": {
"id": 1,
"full_path": "owner/repo",
"full_name": "owner/repo",
"human_name": "repo",
"name": "repo",
"path": "repo",
"description": "Example repository",
"owner": {
"id": "1",
"login": "owner",
"name": "owner",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "owner@example.com",
"name_cn": "Example",
"html_url": "https://api.atomgit.com/owner"
},
"assigner": {
"id": "1",
"login": "owner",
"name": "owner",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "owner@example.com",
"name_cn": "Example",
"html_url": "https://api.atomgit.com/owner"
},
"internal": false,
"html_url": "https://api.atomgit.com/owner/repo"
}
},
"base": {
"label": "owner:main",
"ref": "main",
"sha": "def456abc789",
"user": {
"id": "1",
"login": "owner",
"name": "owner",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "owner@example.com",
"name_cn": "Example",
"html_url": "https://api.atomgit.com/owner"
},
"repo": {
"id": 1,
"full_path": "owner/repo",
"full_name": "owner/repo",
"human_name": "repo",
"name": "repo",
"path": "repo",
"description": "Example repository",
"owner": {
"id": "1",
"login": "owner",
"name": "owner",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "owner@example.com",
"name_cn": "Example",
"html_url": "https://api.atomgit.com/owner"
},
"assigner": {
"id": "1",
"login": "owner",
"name": "owner",
"state": "active",
"avatar_url": "https://api.atomgit.com/avatar.png",
"email": "owner@example.com",
"name_cn": "Example",
"html_url": "https://api.atomgit.com/owner"
},
"internal": false,
"html_url": "https://api.atomgit.com/owner/repo"
}
},
"id": 1,
"iid": 1,
"project_id": 1,
"title": "Example pull request",
"body": "This is the pull request description.",
"state": "open",
"assignees_number": 1,
"testers_number": 0,
"created_at": "2024-11-20T13:00:21+08:00",
"updated_at": "2024-11-20T13:00:21+08:00",
"merged_at": null,
"closed_at": null,
"target_branch": "main",
"source_branch": "feature",
"source_project_id": 1,
"force_remove_source_branch": true,
"web_url": "https://api.atomgit.com/owner/repo/pulls/1",
"merge_request_type": "merge",
"review_mode": "standard",
"added_lines": 120,
"removed_lines": 30,
"diff_refs": {
"base_sha": "def456abc789",
"head_sha": "abc123def456",
"start_sha": "123456abcdef"
},
"notes": 3,
"pipeline_status": "success",
"pipeline_status_with_code_quality": "success",
"source_git_url": "https://api.atomgit.com/octocat/repo.git",
"can_merge_check": true,
"mergeable": true,
"locked": false,
"closed_by": null,
"visibility_reason": "public",
"merged_by": {
"id": "1",
"login": "owner",
"name": "owner",
"avatar_url": "https://api.atomgit.com/avatar.png",
"html_url": "https://api.atomgit.com/owner"
}
}
]
Response example when only_count=true:
{
"all": 1,
"opened": 1,
"closed": 0,
"merged": 0,
"locked": 0
}
Error codes
OpenAPI
{"paths": {"/api/v5/repos/{owner}/{repo}/pulls": {"get": {"tags": ["pull_requests"], "summary": "Get the project pull request list", "responses": {"200": {"content": {"application/json": {"schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "iid": {"type": "integer"}, "url": {"type": "string"}, "base": {"type": "object", "properties": {"ref": {"type": "string"}, "sha": {"type": "string"}, "repo": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "path": {"type": "string"}, "owner": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "assigner": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "html_url": {"type": "string"}, "internal": {"type": "boolean"}, "full_name": {"type": "string"}, "full_path": {"type": "string"}, "human_name": {"type": "string"}, "description": {"type": "string"}}}, "user": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "label": {"type": "string"}}}, "body": {"type": "string"}, "head": {"type": "object", "properties": {"ref": {"type": "string"}, "sha": {"type": "string"}, "repo": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "path": {"type": "string"}, "owner": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "assigner": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "html_url": {"type": "string"}, "internal": {"type": "boolean"}, "full_name": {"type": "string"}, "full_path": {"type": "string"}, "human_name": {"type": "string"}, "description": {"type": "string"}}}, "user": {"type": "object", "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "email": {"type": "string"}, "login": {"type": "string"}, "state": {"type": "string"}, "name_cn": {"type": "string"}, "user_id": {"type": "string"}, "html_url": {"type": "string"}, "object_id": {"type": "string"}, "avatar_url": {"type": "string"}}}, "draft": {"type": "boolean"}, "notes": {"type": "integer"}, "state": {"type": "string"}, "title": {"type": "string"}, "labels": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "color": {"type": "string"}, "created_at": {"type": "string", "description": "Time the label was added"}, "updated_at": {"type": "string"}}}}, "locked": {"type": "boolean"}, "number": {"type": "integer"}, "testers": {"type": "array", "items": {"type": "string"}}, "web_url": {"type": "string"}, "html_url": {"type": "string"}, "assignees": {"type": "array", "items": {"type": "string"}}, "closed_at": {"type": "string", "nullable": true}, "closed_by": {"type": "object", "nullable": true, "properties": {"id": {"type": "integer"}, "name": {"type": "string"}, "email": {"type": "string"}, "state": {"type": "string"}, "iam_id": {"type": "string"}, "name_cn": {"type": "string"}, "web_url": {"type": "string"}, "username": {"type": "string"}, "nick_name": {"type": "string"}, "avatar_url": {"type": "string"}}}, "diff_refs": {"type": "object", "properties": {"base_sha": {"type": "string"}, "head_sha": {"type": "string"}, "start_sha": {"type": "string"}}}, "mergeable": {"type": "boolean"}, "merged_at": {"type": "string", "nullable": true}, "merged_by": {"type": "object", "nullable": true, "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "login": {"type": "string"}, "html_url": {"type": "string"}, "avatar_url": {"type": "string"}}}, "created_at": {"type": "string"}, "project_id": {"type": "integer"}, "updated_at": {"type": "string"}, "added_lines": {"type": "integer"}, "review_mode": {"type": "string"}, "prune_branch": {"type": "boolean"}, "removed_lines": {"type": "integer"}, "source_branch": {"type": "string"}, "target_branch": {"type": "string"}, "source_git_url": {"type": "string"}, "testers_number": {"type": "integer"}, "can_merge_check": {"type": "boolean", "description": "This field is deprecated; if needed, call the pull request details endpoint"}, "pipeline_status": {"type": "string"}, "assignees_number": {"type": "integer"}, "source_project_id": {"type": "integer"}, "visibility_reason": {"type": "string", "description": "Visibility: public means publicly visible, other means visible only to project members"}, "merge_request_type": {"type": "string"}, "close_related_issue": {"type": "integer"}, "force_remove_source_branch": {"type": "boolean"}, "pipeline_status_with_code_quality": {"type": "string"}}}}}}, "description": "Successful response"}}, "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 personal namespace)"}, {"in": "path", "name": "repo", "schema": {"type": "string"}, "required": true, "description": "Repository path (path)"}, {"in": "query", "name": "state", "schema": {"enum": ["all", "open", "closed", "locked", "merged"], "type": "string", "default": "all"}, "description": "Pull request state: all, open, closed, locked, merged; defaults to all"}, {"in": "query", "name": "base", "schema": {"type": "string"}, "description": "Name of the target branch to which the pull request is submitted"}, {"in": "query", "name": "since", "schema": {"type": "string"}, "description": "Start of the update time; the time format must be ISO 8601"}, {"in": "query", "name": "direction", "schema": {"enum": ["asc", "desc"], "type": "string", "default": "desc"}, "description": "Ascending/descending; defaults to desc (asc or desc)"}, {"in": "query", "name": "sort", "schema": {"enum": ["created", "updated"], "type": "string", "default": "created"}, "description": "Sort field: created, updated; defaults to created"}, {"in": "query", "name": "milestone_number", "schema": {"type": "integer"}, "description": "Milestone ordinal number (id)"}, {"in": "query", "name": "labels", "schema": {"type": "string"}, "description": "Comma-separated list of label names"}, {"in": "query", "name": "page", "schema": {"type": "integer", "default": 1}, "description": "Current page number; defaults to 1"}, {"in": "query", "name": "per_page", "schema": {"type": "integer", "default": 20}, "description": "Number of items per page, up to 100; defaults to 20"}, {"in": "query", "name": "author", "schema": {"type": "string"}, "description": "Username of the PR creator"}, {"in": "query", "name": "assignee", "schema": {"type": "string"}, "description": "Username of the PR assignee"}, {"in": "query", "name": "reviewer", "schema": {"type": "string"}, "description": "Username of the PR reviewer"}, {"in": "query", "name": "merged_after", "schema": {"type": "string"}, "description": "Return merge requests merged after the specified time; the time format must be ISO 8601"}, {"in": "query", "name": "merged_before", "schema": {"type": "string"}, "description": "Return merge requests merged before the specified time; the time format must be ISO 8601"}, {"in": "query", "name": "only_count", "schema": {"type": "boolean", "default": false}, "description": "If true, return only the merge request count; defaults to false"}, {"in": "query", "name": "created_after", "schema": {"type": "string"}, "description": "Return merge requests created after the specified time; the time format must be ISO 8601"}, {"in": "query", "name": "created_before", "schema": {"type": "string"}, "description": "Return merge requests created before the specified time; the time format must be ISO 8601"}, {"in": "query", "name": "updated_before", "schema": {"type": "string"}, "description": "Return merge requests updated before the specified time; the time format must be ISO 8601"}, {"in": "query", "name": "updated_after", "schema": {"type": "string"}, "description": "Return merge requests updated after the specified time; the time format must be ISO 8601"}], "description": "The user calls this endpoint to perform the get the project pull request list operation."}}}}