2018-02-24 22:12:11 -05:00
# Project import/export API
2018-02-13 09:04:19 -05:00
2020-01-31 04:08:53 -05:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41899) in GitLab 10.6.
2018-02-13 09:04:19 -05:00
2020-01-31 04:08:53 -05:00
See also:
- [Project import/export documentation ](../user/project/settings/import_export.md ).
- [Project import/export administration rake tasks ](../administration/raketasks/project_import_export.md ). ** (CORE ONLY)**
2018-02-13 09:04:19 -05:00
2018-02-24 22:12:11 -05:00
## Schedule an export
2017-12-05 23:27:23 -05:00
Start a new export.
2020-01-31 04:08:53 -05:00
The endpoint also accepts an `upload` parameter. This parameter is a hash that contains
2018-03-30 11:45:59 -04:00
all the necessary information to upload the exported project to a web server or
to any S3-compatible platform. At the moment we only support binary
data file uploads to the final server.
2020-01-31 04:08:53 -05:00
From GitLab 10.7, the `upload[url]` parameter is required if the `upload` parameter is present.
2018-03-30 11:45:59 -04:00
2019-02-15 04:39:23 -05:00
```text
2017-12-05 23:27:23 -05:00
POST /projects/:id/export
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2018-03-14 10:17:35 -04:00
| `description` | string | no | Overrides the project description |
2018-03-30 11:45:59 -04:00
| `upload` | hash | no | Hash that contains the information to upload the exported project to a web server |
| `upload[url]` | string | yes | The URL to upload the project |
| `upload[http_method]` | string | no | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` |
2017-12-05 23:27:23 -05:00
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/1/export \
2018-07-10 09:55:56 -04:00
--data "upload[http_method]=PUT" \
--data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256& X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request& X-Amz-Date=20180312T110328Z& X-Amz-Expires=900& X-Amz-SignedHeaders=host& X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd"
```
2017-12-05 23:27:23 -05:00
```json
{
"message": "202 Accepted"
}
```
## Export status
Get the status of export.
2019-02-15 04:39:23 -05:00
```text
2017-12-05 23:27:23 -05:00
GET /projects/:id/export
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/1/export
2017-12-05 23:27:23 -05:00
```
2020-01-31 04:08:53 -05:00
Status can be one of:
- `none`
- `started`
- `after_export_action`
- `finished`
The `after_export_action` state represents that the export process has been completed successfully and
2018-03-30 11:45:59 -04:00
the platform is performing some actions on the resulted file. For example, sending
an email notifying the user to download the file, uploading the exported file
to a web server, etc.
2017-12-05 23:27:23 -05:00
2018-02-28 22:30:47 -05:00
`_links` are only present when export has finished.
2017-12-05 23:27:23 -05:00
```json
{
"id": 1,
"description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
"name": "Gitlab Test",
"name_with_namespace": "Gitlab Org / Gitlab Test",
"path": "gitlab-test",
"path_with_namespace": "gitlab-org/gitlab-test",
"created_at": "2017-08-29T04:36:44.383Z",
"export_status": "finished",
"_links": {
"api_url": "https://gitlab.example.com/api/v4/projects/1/export/download",
"web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/download_export",
}
}
```
## Export download
Download the finished export.
2019-02-15 04:39:23 -05:00
```text
2018-02-24 22:12:11 -05:00
GET /projects/:id/export/download
2017-12-05 23:27:23 -05:00
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download
2017-12-05 23:27:23 -05:00
```
2020-01-30 10:09:15 -05:00
```shell
2017-12-05 23:27:23 -05:00
ls *export.tar.gz
2017-12-05_22-11-148_namespace_project_export.tar.gz
```
2018-02-13 09:04:19 -05:00
## Import a file
2019-02-15 04:39:23 -05:00
```text
2018-02-13 09:04:19 -05:00
POST /projects/import
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
2018-02-16 08:37:26 -05:00
| `namespace` | integer/string | no | The ID or path of the namespace that the project will be imported to. Defaults to the current user's namespace |
2019-09-19 20:05:59 -04:00
| `name` | string | no | The name of the project to be imported. Defaults to the path of the project if not provided |
2018-02-13 09:04:19 -05:00
| `file` | string | yes | The file to be uploaded |
| `path` | string | yes | Name and path for new project |
2018-04-06 11:23:49 -04:00
| `overwrite` | boolean | no | If there is a project with the same path the import will overwrite it. Default to false |
2018-04-23 06:29:53 -04:00
| `override_params` | Hash | no | Supports all fields defined in the [Project API ](projects.md ) |
2018-03-29 09:08:31 -04:00
2018-04-23 06:29:53 -04:00
The override params passed will take precedence over all values defined inside the export file.
2018-02-13 09:04:19 -05:00
2018-04-23 06:29:53 -04:00
To upload a file from your file system, use the `--form` argument. This causes
2018-02-13 09:04:19 -05:00
cURL to post data using the header `Content-Type: multipart/form-data` .
2018-04-23 06:29:53 -04:00
The `file=` parameter must point to a file on your file system and be preceded
2018-02-13 09:04:19 -05:00
by `@` . For example:
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import
2018-02-13 09:04:19 -05:00
```
2018-07-10 09:55:56 -04:00
cURL doesn't support posting a file from a remote server. Importing a project from a remote server can be accomplished through something like the following:
```python
import requests
2019-09-19 20:05:59 -04:00
from io import BytesIO
2018-07-10 09:55:56 -04:00
2019-09-19 20:05:59 -04:00
s3_file = requests.get(presigned_url)
2018-07-10 09:55:56 -04:00
url = 'https://gitlab.example.com/api/v4/projects/import'
2019-09-20 02:06:19 -04:00
files = {'file': ('file.tar.gz', BytesIO(s3_file.content))}
2018-07-10 09:55:56 -04:00
data = {
"path": "example-project",
"namespace": "example-group"
}
headers = {
2018-12-27 04:03:08 -05:00
'Private-Token': "< your_access_token > "
2018-07-10 09:55:56 -04:00
}
requests.post(url, headers=headers, data=data, files=files)
```
2018-02-13 09:04:19 -05:00
```json
{
"id": 1,
"description": null,
"name": "api-project",
"name_with_namespace": "Administrator / api-project",
"path": "api-project",
"path_with_namespace": "root/api-project",
"created_at": "2018-02-13T09:05:58.023Z",
"import_status": "scheduled"
}
```
## Import status
2018-02-13 09:12:18 -05:00
Get the status of an import.
2018-02-13 09:04:19 -05:00
2019-02-15 04:39:23 -05:00
```text
2018-02-13 09:04:19 -05:00
GET /projects/:id/import
```
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ---------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/projects/1/import
2018-02-13 09:04:19 -05:00
```
2020-01-31 04:08:53 -05:00
Status can be one of:
- `none`
- `scheduled`
- `failed`
- `started`
- `finished`
2018-02-13 09:12:18 -05:00
2018-02-16 08:37:26 -05:00
If the status is `failed` , it will include the import error message under `import_error` .
2018-02-13 09:04:19 -05:00
```json
{
"id": 1,
"description": "Itaque perspiciatis minima aspernatur corporis consequatur.",
"name": "Gitlab Test",
"name_with_namespace": "Gitlab Org / Gitlab Test",
"path": "gitlab-test",
"path_with_namespace": "gitlab-org/gitlab-test",
"created_at": "2017-08-29T04:36:44.383Z",
"import_status": "started"
}
```