# GitLab Merge trains API

**Canonical:** https://apis.io/apis/gitlab/gitlab-merge-trains-api/  
**Provider:** GitLab — https://apis.io/providers/gitlab/  
**Base URL:** https://gitlab.com/api/v4  
**Documentation:** https://docs.gitlab.com/api/rest/

GitLab Merge trains API is one of 189 APIs that [GitLab](https://apis.io/providers/gitlab/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 16 JSON Schema definitions. Tagged areas include Merge trains. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, authentication docs, an API reference, rate-limit docs, an AsyncAPI specification, and 16 JSON Schemas.

Use this API to retrieve the [merge trains](https://docs.gitlab.com/ci/pipelines/merge_trains/) of a project. These endpoints require the Developer, Maintainer, or Owner role, and support [offset-based pagination](https://docs.gitlab.com/api/rest/#offset-based-pagination). Each object in a response represents one merge request in a train, not an entire train. Requesting merge trains without a target branch can return entries from more than one train in the project. Responses do not include an explicit queue position, and return merge requests as a flat list rather than grouped by train: - For an exact queue position, sort by `id` in ascending order, or use the GraphQL API [`MergeTrainCar.index`](https://docs.gitlab.com/api/graphql/reference/objects/#mergetraincar) field. - To group merge requests by train, use the `target_branch` attribute, or query the GraphQL API [`Project.mergeTrains`](https://docs.gitlab.com/api/graphql/reference/objects/#project) and [`MergeTrain.cars`](https://docs.gitlab.com/api/graphql/reference/objects/#mergetrain) fields.

## Operations (4)

| Method | Path | Summary |
|---|---|---|
| GET | `/api/v4/projects/{id}/merge_trains` | List all merge trains for a project |
| GET | `/api/v4/projects/{id}/merge_trains/{target_branch}` | List all merge requests in a merge train |
| GET | `/api/v4/projects/{id}/merge_trains/merge_requests/{merge_request_iid}` | Retrieve merge train status |
| POST | `/api/v4/projects/{id}/merge_trains/merge_requests/{merge_request_iid}` | Add a merge request to a merge train |

## Machine-readable artifacts (65)

- **OpenAPI** — https://artifacts.apis.io/gitlab/openapi/gitlab-merge-trains-api-openapi.yml
- **Documentation** — https://docs.gitlab.com/api/openapi/
- **Documentation** — https://docs.gitlab.com/api/issues/
- **Authentication** — https://docs.gitlab.com/api/rest/authentication/
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-application-settings-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-node-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-geo-site-status-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-apientities-application-setting-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-post-api-v4-geo-status-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/gitlab/json-schema/gitlab-put-api-v4-projects-id-request-schema.json
- **Documentation** — https://docs.gitlab.com/api/merge_requests/
- **Documentation** — https://docs.gitlab.com/api/pipelines/
- **Documentation** — https://docs.gitlab.com/api/jobs/
- **Documentation** — https://docs.gitlab.com/api/runners/
- **Documentation** — https://docs.gitlab.com/api/users/
- **Documentation** — https://docs.gitlab.com/api/repositories/
- **Documentation** — https://docs.gitlab.com/api/commits/
- **Documentation** — https://docs.gitlab.com/api/branches/
- **Documentation** — https://docs.gitlab.com/api/tags/
- **Documentation** — https://docs.gitlab.com/api/releases/
- **Documentation** — https://docs.gitlab.com/api/environments/
- **Documentation** — https://docs.gitlab.com/api/deployments/
- **Documentation** — https://docs.gitlab.com/api/pipeline_schedules/
- **Documentation** — https://docs.gitlab.com/api/labels/
- **Documentation** — https://docs.gitlab.com/api/milestones/
- **Documentation** — https://docs.gitlab.com/api/notes/
- **Documentation** — https://docs.gitlab.com/api/snippets/
- **Documentation** — https://docs.gitlab.com/api/packages/
- **Documentation** — https://docs.gitlab.com/api/container_registry/
- **Documentation** — https://docs.gitlab.com/api/vulnerabilities/
- **Documentation** — https://docs.gitlab.com/api/deploy_keys/
- **Documentation** — https://docs.gitlab.com/api/protected_branches/
- **Documentation** — https://docs.gitlab.com/api/wikis/
- **Documentation** — https://docs.gitlab.com/api/events/
- **Documentation** — https://docs.gitlab.com/api/search/
- **Documentation** — https://docs.gitlab.com/api/namespaces/
- **Documentation** — https://docs.gitlab.com/api/groups/
- **Documentation** — https://docs.gitlab.com/api/projects/
- **Documentation** — https://docs.gitlab.com/api/applications/
- **Documentation** — https://docs.gitlab.com/api/avatar/
- …and 25 more, listed in full on the page.

## Other GitLab APIs (12)

- [GitLab Orbit gRPC API](https://apis.io/apis/gitlab/gitlab-orbit-api/)
- [GitLab GraphQL API](https://apis.io/apis/gitlab/gitlab-graphql-api/)
- [GitLab Applications API](https://apis.io/apis/gitlab/gitlab-applications-api/)
- [GitLab Authorization API](https://apis.io/apis/gitlab/gitlab-authorization-api/)
- [GitLab Broadcast Messages API](https://apis.io/apis/gitlab/gitlab-broadcast-messages-api/)
- [GitLab Groups API](https://apis.io/apis/gitlab/gitlab-groups-api/)
- [GitLab Metadata API](https://apis.io/apis/gitlab/gitlab-metadata-api/)
- [GitLab Project Webhooks API](https://apis.io/apis/gitlab/gitlab-project-webhooks-api/)
- [GitLab Projects API](https://apis.io/apis/gitlab/gitlab-projects-api/)
- [GitLab Tokens API](https://apis.io/apis/gitlab/gitlab-tokens-api/)
- [GitLab User Info API](https://apis.io/apis/gitlab/gitlab-user-info-api/)
- [GitLab Webhook Configuration API](https://apis.io/apis/gitlab/gitlab-webhook-configuration-api/)

## Tags

Merge trains

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/gitlab/gitlab-merge-trains-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/gitlab/.