Topics API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Interact with project topics using the REST API.
List topics
Returns a list of project topics in the GitLab instance ordered by number of associated projects.
GET /topics
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
page | integer | No | Page to retrieve. Defaults to 1 . |
per_page | integer | No | Number of records to return per page. Defaults to 20 . |
search | string | No | Search topics against their name . |
without_projects | boolean | No | Limit results to topics without assigned projects. |
Example request:
curl "https://gitlab.example.com/api/v4/topics?search=git"
Example response:
[
{
"id": 1,
"name": "gitlab",
"title": "GitLab",
"description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
"total_projects_count": 1000,
"organization_id": 1,
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
},
{
"id": 3,
"name": "git",
"title": "Git",
"description": "Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.",
"total_projects_count": 900,
"organization_id": 1,
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon"
},
{
"id": 2,
"name": "git-lfs",
"title": "Git LFS",
"description": null,
"total_projects_count": 300,
"organization_id": 1,
"avatar_url": null
}
]
Get a topic
Get a project topic by ID.
GET /topics/:id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | Yes | ID of project topic |
Example request:
curl "https://gitlab.example.com/api/v4/topics/1"
Example response:
{
"id": 1,
"name": "gitlab",
"title": "GitLab",
"description": "GitLab is an open source end-to-end software development platform with built-in version control, issue tracking, code review, CI/CD, and more.",
"total_projects_count": 1000,
"organization_id": 1,
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
}
List projects assigned to a topic
Use the Projects API to list all projects assigned to a specific topic.
GET /projects?topic=<topic_name>
Create a project topic
Create a new project topic. Only available to administrators.
POST /topics
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
name | string | Yes | Slug (name) |
title | string | Yes | Title |
avatar | file | No | Avatar |
description | string | No | Description |
organization_id | integer | No | The organization ID for the topic. Warning: this attribute is experimental and a subject to change in future. For more information on organizations, see Organizations API |
Example request:
curl --request POST \
--data "name=topic1&title=Topic 1" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics"
Example response:
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"organization_id": 1,
"avatar_url": null
}
Update a project topic
Update a project topic. Only available to administrators.
PUT /topics/:id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | Yes | ID of project topic |
avatar | file | No | Avatar |
description | string | No | Description |
name | string | No | Slug (name) |
title | string | No | Title |
Example request:
curl --request PUT \
--data "name=topic1" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
Example response:
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"organization_id": 1,
"avatar_url": null
}
Upload a topic avatar
To upload an avatar file from your file system, use the --form
argument. This argument causes
cURL to post data using the header Content-Type: multipart/form-data
. The
file=
parameter must point to a file on your file system and be preceded by
@
. For example:
curl --request PUT \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1" \
--form "avatar=@/tmp/example.png"
Remove a topic avatar
To remove a topic avatar, use a blank value for the avatar
attribute.
Example request:
curl --request PUT \
--data "avatar=" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
Delete a project topic
You must be an administrator to delete a project topic. When you delete a project topic, you also delete the topic assignment for projects.
DELETE /topics/:id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | Yes | ID of project topic |
Example request:
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
Merge topics
You must be an administrator to merge a source topic into a target topic. When you merge topics, you delete the source topic and move all assigned projects to the target topic.
POST /topics/merge
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
source_topic_id | integer | Yes | ID of source project topic |
target_topic_id | integer | Yes | ID of target project topic |
The source_topic_id
and target_topic_id
must belong to the same organization.
Example request:
curl --request POST \
--data "source_topic_id=2&target_topic_id=1" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/merge"
Example response:
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"organization_id": 1,
"avatar_url": null
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support