gitlab-org--gitlab-foss/doc/api/topics.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

280 lines
7.5 KiB
Markdown
Raw Normal View History

---
stage: Manage
group: Workspace
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Topics API **(FREE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340920) in GitLab 14.5.
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.
```plaintext
GET /topics
```
Supported attributes:
| Attribute | Type | Required | Description |
| ------------------ | ------- | ---------------------- | ----------- |
| `page` | integer | **{dotted-circle}** No | Page to retrieve. Defaults to `1`. |
| `per_page` | integer | **{dotted-circle}** No | Number of records to return per page. Defaults to `20`. |
| `search` | string | **{dotted-circle}** No | Search topics against their `name`. |
| `without_projects` | boolean | **{dotted-circle}** No | Limit results to topics without assigned projects. |
Example request:
```shell
curl "https://gitlab.example.com/api/v4/topics?search=git"
```
Example response:
```json
[
{
"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,
"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,
"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,
"avatar_url": null
}
]
```
## Get a topic
Get a project topic by ID.
```plaintext
GET /topics/:id
```
Supported attributes:
| Attribute | Type | Required | Description |
| --------- | ------- | ---------------------- | ------------------- |
| `id` | integer | **{check-circle}** Yes | ID of project topic |
Example request:
```shell
curl "https://gitlab.example.com/api/v4/topics/1"
```
Example response:
```json
{
"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,
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon"
}
```
## List projects assigned to a topic
Use the [Projects API](projects.md#list-all-projects) to list all projects assigned to a specific topic.
```plaintext
GET /projects?topic=<topic_name>
```
## Create a project topic
Create a new project topic. Only available to administrators.
```plaintext
POST /topics
```
Supported attributes:
| Attribute | Type | Required | Description |
| ------------- | ------- | ---------------------- | ----------- |
| `name` | string | **{check-circle}** Yes | Slug (name) |
| `title` | string | **{check-circle}** Yes | Title |
| `avatar` | file | **{dotted-circle}** No | Avatar |
| `description` | string | **{dotted-circle}** No | Description |
Example request:
```shell
curl --request POST \
--data "name=topic1&title=Topic 1" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics"
```
Example response:
```json
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"avatar_url": null
}
```
## Update a project topic
Update a project topic. Only available to administrators.
```plaintext
PUT /topics/:id
```
Supported attributes:
| Attribute | Type | Required | Description |
| ------------- | ------- | ---------------------- | ------------------- |
| `id` | integer | **{check-circle}** Yes | ID of project topic |
| `avatar` | file | **{dotted-circle}** No | Avatar |
| `description` | string | **{dotted-circle}** No | Description |
| `name` | string | **{dotted-circle}** No | Slug (name) |
| `title` | string | **{dotted-circle}** No | Title |
Example request:
```shell
curl --request PUT \
--data "name=topic1" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
```
Example response:
```json
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"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:
```shell
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
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/348148) in GitLab 14.6.
To remove a topic avatar, use a blank value for the `avatar` attribute.
Example request:
```shell
curl --request PUT \
--data "avatar=" \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
```
## Delete a project topic
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80725) in GitLab 14.9.
You must be an administrator to delete a project topic.
When you delete a project topic, you also delete the topic assignment for projects.
```plaintext
DELETE /topics/:id
```
Supported attributes:
| Attribute | Type | Required | Description |
| ------------- | ------- | ---------------------- | ------------------- |
| `id` | integer | **{check-circle}** Yes | ID of project topic |
Example request:
```shell
curl --request DELETE \
--header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/topics/1"
```
## Merge topics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95501) in GitLab 15.4.
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.
```plaintext
POST /topics/merge
```
Supported attributes:
| Attribute | Type | Required | Description |
| ----------------- | ------- | ---------------------- | -------------------------- |
| `source_topic_id` | integer | **{check-circle}** Yes | ID of source project topic |
| `target_topic_id` | integer | **{check-circle}** Yes | ID of target project topic |
Example request:
```shell
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:
```json
{
"id": 1,
"name": "topic1",
"title": "Topic 1",
"description": null,
"total_projects_count": 0,
"avatar_url": null
}
```