---
title: "Create a milestone"
method: POST
path: "/repos/{owner}/{repo}/milestones"
tags: ["issue"]
---

# Create a milestone

`POST /repos/{owner}/{repo}/milestones`

## Request

- Base URL: `https://demo.gitea.com/api/v1`
- URL: `https://demo.gitea.com/api/v1/repos/{owner}/{repo}/milestones`
- Auth: one of:
  - HTTP basic
  - API key in query parameter `token`
  - API key in query parameter `access_token`
  - API key in header `Authorization`
  - API key in query parameter `sudo`
  - API key in header `Sudo`
  - API key in header `X-GITEA-OTP`
- TypeScript: <https://skmtc.dev/gitea/apis/gitea-api/docs/repos/:owner/:repo/milestones/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `owner` string, required
- `repo` string, required

## Request body

- CreateMilestoneOption: CreateMilestoneOption options for creating a milestone
  - `description` string: Description provides details about the milestone
  - `due_on` string, date-time: Deadline is the due date for the milestone
  - `state` 'open' | 'closed': State indicates the initial state of the milestone
  - `title` string: Title is the title of the new milestone

## Response `201`

Milestone

- Milestone: Milestone is a collection of issues on one repository
  - `closed_at` string, date-time
  - `closed_issues` integer: ClosedIssues is the number of closed issues in this milestone
  - `created_at` string, date-time
  - `description` string: Description provides details about the milestone
  - `due_on` string, date-time
  - `id` integer: ID is the unique identifier for the milestone
  - `open_issues` integer: OpenIssues is the number of open issues in this milestone
  - `state` 'open' | 'closed': State indicates if the milestone is open or closed
  - `title` string: Title is the title of the milestone
  - `updated_at` string, date-time

## Other responses

- `default`: APIError is error format response

## Changes

- **2026-10-28** `7ef50c4c527f`: 1 info
  - removed the non-success response with the status `404`

[Operation history](https://skmtc.dev/gitea/apis/gitea-api/changes/repos/:owner/:repo/milestones/post.md)

---

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