---
title: "Create a runner"
method: POST
path: "/api/v4/runners"
tags: ["ci_runners"]
---

# Create a runner

`POST /api/v4/runners`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/runners`
- Auth: none declared

Creates a runner.

## Request body

- PostApiV4Runners: Create a runner
  - `token` string, required: Registration token
  - `description` string: Description of the runner
  - `maintainer_note` string: Deprecated: see `maintenance_note`
  - `maintenance_note` string: Free-form maintenance notes for the runner (1024 characters)
  - `info` object: Runner's metadata
    - `name` string: Runner's name
    - `version` string: Runner's version
    - `revision` string: Runner's revision
    - `platform` string: Runner's platform
    - `architecture` string: Runner's architecture
  - `active` boolean: Deprecated: Use `paused` instead. Specifies if the runner is allowed to receive new jobs
  - `paused` boolean: Specifies if the runner should ignore new jobs
  - `locked` boolean: Specifies if the runner should be locked for the current project
  - `access_level` 'not_protected' | 'ref_protected': The access level of the runner
  - `run_untagged` boolean: Specifies if the runner should handle untagged jobs
  - `tag_list` string[]: A list of runner tags
  - `maximum_timeout` integer: Maximum timeout that limits the amount of time (in seconds) that runners can run jobs

## Response `201`

Create a runner

- APIEntitiesCiRunnerRegistrationDetails: API_Entities_Ci_RunnerRegistrationDetails model
  - `id` string, required
  - `token` string, required
  - `token_expires_at` string, required

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `410`: Gone

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)