Search by type¶

GET /api/v5/search

Search across the whole site for the type given by type; returns a result list with a unified pagination structure. The type decides the structure of each element in content (repository, user, organization, merge request, or issue).

Access token support¶

AtomGit user access token (AtomGit user access tokens)

Anonymous access¶

This endpoint allows anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`type`	query	string	Yes	Search type, enum: `repo`, `user`, `group`, `pullrequest`, `issue`; case-insensitive; an unsupported value returns `400`
`q`	query	string	No	Search keyword; the source code does not validate it as required, so it can be omitted
`repo_type`	query	string[]	No	Repository type: `0` code repository, `1` model repository, `2` dataset repository; multiple values are allowed
`task`	query	string	No	Task label, such as `text-generation`; separate multiple values with commas; only takes effect for model repository searches
`library`	query	string	No	Framework library label, such as `transformers`; separate multiple values with commas; only takes effect for model repository searches
`param.min`	query	string	No	Lower bound of the parameter size, such as `1B`; if neither it nor `param.max` is passed, no parameter size filter is applied
`param.max`	query	string	No	Upper bound of the parameter size, such as `7B`
`s`	query	string	No	Sort field, such as `created_at`, `updated_at`, `star`, `fork`; when omitted, results are sorted by best match
`o`	query	string	No	Sort order: `asc` ascending, `desc` descending
`p`	query	integer	No	Page number, default `1`
`pp`	query	integer	No	Number of items per page, default `10`

Response parameters¶

Field	Type	Always returned	Nullable	Description
`page_num`	integer	Yes	No	Current page number
`page_size`	integer	Yes	No	Number of items returned per page
`total`	integer	Yes	No	Total number of matching results
`page_count`	integer	Yes	No	Total number of pages, computed from `total` and `page_size`
`content`	object[]	Yes	No	Search result list; the element structure varies with `type`, see the type-specific objects below

content element fields common to all types

Field	Type	Always returned	Nullable	Description
`content[].url`	string	Yes	Yes	Page URL of the result
`content[].created_at`	string	Yes	Yes	Creation time, format `yyyy-MM-dd HH:mm:ss` (UTC+8)
`content[].updated_at`	string	Yes	Yes	Update time, format `yyyy-MM-dd HH:mm:ss` (UTC+8)

`content` element for `type=repo` (repository, model repository, dataset repository, space)¶

Field	Type	Always returned	Nullable	Description
`content[].id`	string	Yes	Yes	Repository id
`content[].name`	string	Yes	Yes	Repository name
`content[].description`	string	Yes	Yes	Repository description
`content[].project_type`	string	Yes	Yes	Project type: `code` / `model` / `dataset` / `space` / `ugr`
`content[].name_with_namespace`	string	Yes	Yes	Full-path name, including the organization or personal name
`content[].path_with_namespace`	string	Yes	Yes	Full path, including the organization or personal path
`content[].language`	string	Yes	Yes	Repository language
`content[].show_recommend_icon`	boolean	Yes	Yes	Whether to show the GitHub recommendation icon
`content[].import_star_count`	integer	Yes	Yes	Star count of the imported mirror repository
`content[].namespace`	string	Yes	Yes	Repository namespace
`content[].path`	string	Yes	Yes	Repository path
`content[].web_url`	string	Yes	Yes	Web URL
`content[].star_count`	integer	Yes	Yes	Star count
`content[].forks_count`	integer	Yes	Yes	Fork count
`content[].default_branches`	string	Yes	Yes	Default branch
`content[].last_activity_at`	string	Yes	Yes	Most recent activity time
`content[].main_language`	string	Yes	Yes	Primary repository language
`content[].license`	object	Yes	Yes	Open source license information of the repository, see the `license` object below
`content[].last_repository_updated_at`	string	Yes	Yes	Most recent update time of the repository
`content[].repo_type`	string	Yes	Yes	Repository type: `code` / `model` / `dataset` / `space`
`content[].task`	object[]	Yes	Yes	List of model task labels, see the `task` / `library` element below
`content[].library`	object[]	Yes	Yes	List of model framework labels, see the `task` / `library` element below
`content[].model_param_size`	string	Yes	Yes	Model parameter size
`content[].archived`	boolean	Yes	Yes	Whether it is archived
`content[].avatar_url`	string	Yes	Yes	Project avatar
`content[].visibility`	string	Yes	Yes	Visibility: `public` / `private`
`content[].creator`	object	Yes	Yes	Project creator, see the `creator` object below

`content[].license` object¶

Field	Type	Always returned	Nullable	Description
`content[].license.key`	string	Yes	Yes	License key
`content[].license.name`	string	Yes	Yes	License name
`content[].license.nickname`	string	Yes	Yes	License alias
`content[].license.html_url`	string	Yes	Yes	License HTML link
`content[].license.source_url`	string	Yes	Yes	License source link

`content[].creator` object¶

Field	Type	Always returned	Nullable	Description
`content[].creator.id`	integer	Yes	Yes	User id
`content[].creator.name`	string	Yes	Yes	Name
`content[].creator.username`	string	Yes	Yes	Username
`content[].creator.avatar_url`	string	Yes	Yes	Avatar URL
`content[].creator.web_url`	string	Yes	Yes	User homepage URL
`content[].creator.nick_name`	string	Yes	Yes	Nickname

`content[].task` / `content[].library` element¶

Field	Type	Always returned	Nullable	Description
`content[].task[].code`	string	Yes	Yes	Label code
`content[].task[].name`	string	Yes	Yes	Label name

Note: The element structure of content[].library is identical to that of content[].task, with the same code and name fields.

`content` element for `type=user` (user)¶

Field	Type	Always returned	Nullable	Description
`content[].id`	string	Yes	Yes	User object id
`content[].username`	string	Yes	Yes	Username
`content[].nickname`	string	Yes	Yes	User nickname
`content[].avatar_url`	string	Yes	Yes	Avatar URL
`content[].description`	string	Yes	Yes	User bio
`content[].location`	string	Yes	Yes	Location

`content` element for `type=group` (organization)¶

Field	Type	Always returned	Nullable	Description
`content[].id`	string	Yes	Yes	Organization id
`content[].name`	string	Yes	Yes	Organization name
`content[].full_name`	string	Yes	Yes	Full organization name
`content[].full_path`	string	Yes	Yes	Full organization path
`content[].description`	string	Yes	Yes	Organization description
`content[].avatar`	string	Yes	Yes	Organization avatar
`content[].visibility_level`	string	Yes	Yes	Visibility: `public` / `private`
`content[].follow_num`	integer	Yes	Yes	Follow count
`content[].project_num`	integer	Yes	Yes	Project count
`content[].watch_num`	integer	Yes	Yes	Watch count, returned only for promoted organizations
`content[].fork_num`	integer	Yes	Yes	Fork count, returned only for promoted organizations
`content[].star_num`	integer	Yes	Yes	Star count, returned only for promoted organizations

`content` element for `type=issue` (issue)¶

Field	Type	Always returned	Nullable	Description
`content[].id`	string	Yes	Yes	Issue id
`content[].title`	string	Yes	Yes	Issue title
`content[].description`	string	Yes	Yes	Issue description
`content[].iid`	integer	Yes	Yes	Issue sequence number within the project
`content[].state`	string	Yes	Yes	State: `opened` / `closed` / `rejected`
`content[].author`	object	Yes	Yes	Issue author, see the `author` object below
`content[].labels`	string[]	Yes	Yes	List of labels
`content[].path_with_namespace`	string	Yes	Yes	Full project path
`content[].project_url`	string	Yes	Yes	Project URL
`content[].comment_num`	integer	Yes	Yes	Number of comments

`content` element for `type=pullrequest` (merge request)¶

Field	Type	Always returned	Nullable	Description
`content[].id`	string	Yes	Yes	PR id
`content[].iid`	integer	Yes	Yes	PR sequence number within the project
`content[].title`	string	Yes	Yes	PR title
`content[].description`	string	Yes	Yes	PR description
`content[].target_branch`	string	Yes	Yes	Target branch
`content[].source_branch`	string	Yes	Yes	Source branch
`content[].comment_num`	integer	Yes	Yes	Number of comments
`content[].labels`	string[]	Yes	Yes	List of labels
`content[].state`	string	Yes	Yes	State: `open` / `merged` / `closed`
`content[].author`	object	Yes	Yes	PR author, see the `author` object below
`content[].path_with_namespace`	string	Yes	Yes	Full project path
`content[].project_url`	string	Yes	Yes	Project URL

`content[].author` object (`type=issue` / `type=pullrequest`)¶

Field	Type	Always returned	Nullable	Description
`content[].author.id`	integer	Yes	Yes	User id
`content[].author.name`	string	Yes	Yes	Name
`content[].author.username`	string	Yes	Yes	Username
`content[].author.avatar_url`	string	Yes	Yes	Avatar URL
`content[].author.web_url`	string	Yes	Yes	User homepage URL
`content[].author.nick_name`	string	Yes	Yes	Nickname

Note: Entries in the response are output according to an allowlist and contain only the fields listed in the tables above; fields not used by a given type do not appear.

Error responses¶

When the type value is unsupported (does not match repo, user, group, pullrequest, or issue), parameter validation fails and the global exception handler returns 400:

400 Invalid parameters

{
  "error_code": 400,
  "error_code_name": "PARAMETER_ERROR",
  "error_message": "type only supports repo, user, group, pullrequest, issue",
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

401 Unauthenticated

{
  "error_code": 401,
  "error_code_name": "UNAUTHORIZED",
  "error_message": "Missing or invalid access token",
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

This endpoint allows anonymous access, but an invalid access token still returns 401.

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (for example, an unsupported `type` value)
`401`	Unauthenticated or invalid credentials
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Request example¶

Parameter description¶

The example searches with type=repo and passes the required type parameter.

Replace <q> with the keyword to search, such as vue; replace <token> with your AtomGit user access token. This endpoint allows anonymous access, so the example works without an authentication header; to search as a specific user, add the Authorization: Bearer <token> request header.

cURL¶

curl -X GET 'https://api.atomgit.com/api/v5/search?type=repo&q=<q>&p=1&pp=10' \
  -H 'Accept: application/json'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const params = new URLSearchParams({
  type: "repo",
  q: "<q>",
  p: "1",
  pp: "10",
});

const response = await fetch(`https://api.atomgit.com/api/v5/search?${params}`, {
  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/search",
    params={"type": "repo", "q": "<q>", "p": 1, "pp": 10},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "page_num": 1,
  "page_size": 10,
  "total": 1,
  "page_count": 1,
  "content": [
    {
      "url": "https://api.atomgit.com/api/v5/repos/youlai/vue3-element-admin",
      "created_at": "2024-11-07 18:11:23",
      "updated_at": "2024-11-15 09:20:11",
      "id": "3771502",
      "name": "vue3-element-admin",
      "description": "Vue3 admin framework from Youlai Open Source Organization",
      "project_type": "code",
      "name_with_namespace": "Youlai Open Source Organization / vue3-element-admin",
      "path_with_namespace": "youlai/vue3-element-admin",
      "language": "Vue",
      "show_recommend_icon": false,
      "import_star_count": 0,
      "namespace": "youlai",
      "path": "vue3-element-admin",
      "web_url": "https://api.atomgit.com/youlai/vue3-element-admin",
      "star_count": 128,
      "forks_count": 32,
      "default_branches": "master",
      "last_activity_at": "2024-11-15 09:20:11",
      "main_language": "Vue",
      "license": {
        "key": "mit",
        "name": "MIT License",
        "nickname": "MIT",
        "html_url": "https://api.atomgit.com/youlai/vue3-element-admin/blob/master/LICENSE",
        "source_url": "https://opensource.org/licenses/MIT"
      },
      "last_repository_updated_at": "2024-11-15 09:20:11",
      "repo_type": "code",
      "task": [],
      "library": [],
      "model_param_size": null,
      "archived": false,
      "avatar_url": "https://api.atomgit.com/avatar.png",
      "visibility": "public",
      "creator": {
        "id": 6553,
        "name": "Youlai Tech",
        "username": "youlai",
        "avatar_url": "https://api.atomgit.com/avatar.png",
        "web_url": "https://api.atomgit.com/youlai",
        "nick_name": "Youlai Tech"
      }
    }
  ]
}

Error codes¶

Error code	Description
`400`	Invalid parameters, such as an unsupported `type` value or a wrong parameter type
`401`	Unauthenticated or invalid credentials (an invalid access token was sent)
`404`	Request 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