Create a repository milestone¶

POST /api/v5/repos/{owner}/{repo}/milestones

This endpoint creates a milestone in the specified repository. It supports setting the milestone title, description, due date, and state, and returns the complete information of the created milestone.

Access token support¶

AtomGit user access token (AtomGit user access tokens)

Anonymous access¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Address of the namespace that owns the repository (the address path of an enterprise, organization, or personal namespace)
`repo`	path	string	Yes	Repository path (path)
`access_token`	query	string	Yes	User authorization code

Request Body:

The request body is submitted as JSON or a form. JSON requests must set the Content-Type: application/json header. The value rules for fields are subject to the source code.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "description": "Milestone title",
      "type": "string",
      "minLength": 1
    },
    "description": {
      "description": "Detailed milestone description",
      "type": "string"
    },
    "due_on": {
      "description": "Milestone due date",
      "type": "string",
      "format": "date",
      "minLength": 1
    },
    "state": {
      "description": "Milestone state",
      "type": "string"
    }
  },
  "required": ["title", "due_on"]
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`closed_issues`	integer	Yes	Yes	Number of closed issues
`created_at`	string	Yes	Yes	Creation time
`description`	string	Yes	Yes	Description
`due_on`	string	Yes	Yes	Due date
`html_url`	string	Yes	Yes	HTML address
`number`	integer	Yes	Yes	Number
`id`	integer	Yes	Yes	id
`open_issues`	integer	Yes	Yes	Number of open issues
`repository_id`	integer	Yes	Yes	Repository id
`state`	string	Yes	Yes	State
`title`	string	Yes	Yes	Title
`updated_at`	string	Yes	Yes	Update time
`url`	string	Yes	Yes	url

Error response¶

Besides the success response, callers also need to understand the shape of failures in order to write error-handling logic.

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "Parameter title cannot be empty",
  "field": "title"
}

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

403 No permission

{
  "error": "forbidden",
  "message": "You do not have permission to perform this operation"
}

HTTP response status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid request parameters or the request cannot be parsed
`401`	Requires authentication
`403`	Forbidden

Request example¶

Parameter description¶

Replace <owner> with the address of the namespace that owns the repository (the address path of an enterprise, organization, or personal namespace); replace <repo> with the repository path (path); replace <token> with your AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/milestones?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "title": "Milestone title",
    "description": "Detailed milestone description",
    "due_on": "2026-01-31"
  }'

JavaScript¶

// Native fetch (Node.js 18+ / browser)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/milestones?access_token=<token>",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    body: JSON.stringify({
      title: "Milestone title",
      description: "Detailed milestone description",
      due_on: "2026-01-31"
    })
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/milestones",
    params={"access_token": "<token>"},
    json={
        "title": "Milestone title",
        "description": "Detailed milestone description",
        "due_on": "2026-01-31",
    },
    headers={
        "Accept": "application/json",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "closed_issues": 0,
  "created_at": "2024-10-08T10:58:16+08:00",
  "description": "Hello China",
  "due_on": "2024-11-08",
  "html_url": "https://api.atomgit.com/dengmengmian/oneapi/milestones/1",
  "number": 4914,
  "id": 4066481,
  "open_issues": 0,
  "repository_id": 4066481,
  "state": "active",
  "title": "Hello China",
  "updated_at": "2024-10-08T10:58:16+08:00",
  "url": "https://api.atomgit.com/dengmengmian/oneapi/milestones/1"
}

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing/invalid access token)
`403`	No permission to perform this operation
`404`	The request path does not exist
`405`	The request method is not supported
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc