Add a field to an organization-owned project.

POST

/orgs/{org}/projectsV2/{project_number}/fields

API method documentation

Parameters

Path Parameters

project_number

required

integer

The project’s number.

org

required

string

The organization name. The name is not case sensitive.

Request Body^required

application/json

One of:

object

issue_field_id

required

The ID of the IssueField to create the field for.

integer

Examples

Create a text field

{
  "name": "Team notes",
  "data_type": "text"
}

Create a number field

{
  "name": "Story points",
  "data_type": "number"
}

Create a date field

{
  "name": "Due date",
  "data_type": "date"
}

Create a single select field

{
  "name": "Priority",
  "data_type": "single_select",
  "single_select_options": [
    {
      "name": {
        "raw": "Low",
        "html": "Low"
      },
      "color": "GREEN",
      "description": {
        "raw": "Low priority items",
        "html": "Low priority items"
      }
    },
    {
      "name": {
        "raw": "Medium",
        "html": "Medium"
      },
      "color": "YELLOW",
      "description": {
        "raw": "Medium priority items",
        "html": "Medium priority items"
      }
    },
    {
      "name": {
        "raw": "High",
        "html": "High"
      },
      "color": "RED",
      "description": {
        "raw": "High priority items",
        "html": "High priority items"
      }
    }
  ]
}

Create an iteration field

{
  "name": "Sprint",
  "data_type": "iteration",
  "iteration_configuration": {
    "start_day": 1,
    "duration": 14,
    "iterations": [
      {
        "title": {
          "raw": "Sprint 1",
          "html": "Sprint 1"
        },
        "start_date": "2022-07-01",
        "duration": 14
      },
      {
        "title": {
          "raw": "Sprint 2",
          "html": "Sprint 2"
        },
        "start_date": "2022-07-15",
        "duration": 14
      }
    ]
  }
}

Responses

201

Response for adding a field to an organization-owned project.

application/json

Projects v2 Field

A field inside a projects v2 project

object

required

The unique identifier of the field.

integer

issue_field_id

The ID of the issue field.

integer

node_id

The node ID of the field.

string

project_url

required

The API URL of the project that contains the field.

string

name

required

The name of the field.

string

data_type

required

The field’s data type.

string

Allowed values: assignees linked_pull_requests reviewers labels milestone repository title text single_select number date iteration issue_type parent_issue sub_issues_progress

options

The options available for single select fields.

Array<object>

Projects v2 Single Select Option

An option for a single select field

object

required

The unique identifier of the option.

string

name

required

The display name of the option, in raw text and HTML formats.

object

raw

required

string

html

required

string

description

required

The description of the option, in raw text and HTML formats.

object

raw

required

string

html

required

string

color

required

The color associated with the option.

string

configuration

Configuration for iteration fields.

object

start_day

The day of the week when the iteration starts.

integer

duration

The duration of the iteration in days.

integer

iterations

Array<object>

Projects v2 Iteration Setting

An iteration setting for an iteration field

object

required

The unique identifier of the iteration setting.

string

start_date

required

The start date of the iteration.

string format: date

duration

required

The duration of the iteration in days.

integer

title

required

The iteration title, in raw text and HTML formats.

object

raw

required

string

html

required

string

completed

required

Whether the iteration has been completed.

boolean

created_at

required

The time when the field was created.

string format: date-time

updated_at

required

The time when the field was last updated.

string format: date-time

Examples

{
  "id": 24680,
  "node_id": "PVTF_lADOABCD2468024680",
  "name": "Team notes",
  "data_type": "text",
  "project_url": "https://api.github.com/projects/67890",
  "created_at": "2022-05-15T08:00:00Z",
  "updated_at": "2022-05-15T08:00:00Z"
}

{
  "id": 13579,
  "node_id": "PVTF_lADOABCD1357913579",
  "name": "Story points",
  "data_type": "number",
  "project_url": "https://api.github.com/projects/67890",
  "created_at": "2022-06-01T14:30:00Z",
  "updated_at": "2022-06-01T14:30:00Z"
}

{
  "id": 98765,
  "node_id": "PVTF_lADOABCD9876598765",
  "name": "Due date",
  "data_type": "date",
  "project_url": "https://api.github.com/projects/67890",
  "created_at": "2022-06-10T09:15:00Z",
  "updated_at": "2022-06-10T09:15:00Z"
}

{
  "id": 12345,
  "node_id": "PVTF_lADOABCD1234567890",
  "name": "Priority",
  "data_type": "single_select",
  "project_url": "https://api.github.com/projects/67890",
  "options": [
    {
      "id": "option_1",
      "name": {
        "html": "Low",
        "raw": "Low"
      },
      "color": "GREEN",
      "description": {
        "html": "Low priority items",
        "raw": "Low priority items"
      }
    },
    {
      "id": "option_2",
      "name": {
        "html": "Medium",
        "raw": "Medium"
      },
      "color": "YELLOW",
      "description": {
        "html": "Medium priority items",
        "raw": "Medium priority items"
      }
    },
    {
      "id": "option_3",
      "name": {
        "html": "High",
        "raw": "High"
      },
      "color": "RED",
      "description": {
        "html": "High priority items",
        "raw": "High priority items"
      }
    }
  ],
  "created_at": "2022-04-28T12:00:00Z",
  "updated_at": "2022-04-28T12:00:00Z"
}

{
  "id": 11223,
  "node_id": "PVTF_lADOABCD1122311223",
  "name": "Sprint",
  "data_type": "iteration",
  "project_url": "https://api.github.com/projects/67890",
  "configuration": {
    "duration": 14,
    "start_day": 1,
    "iterations": [
      {
        "id": "iter_1",
        "title": {
          "html": "Sprint 1",
          "raw": "Sprint 1"
        },
        "start_date": "2022-07-01",
        "duration": 14
      },
      {
        "id": "iter_2",
        "title": {
          "html": "Sprint 2",
          "raw": "Sprint 2"
        },
        "start_date": "2022-07-15",
        "duration": 14
      }
    ]
  },
  "created_at": "2022-06-20T16:45:00Z",
  "updated_at": "2022-06-20T16:45:00Z"
}

304

Not modified

401

Requires authentication

application/json

Basic Error

Basic Error

object

message

string

documentation_url

string

url

string

status

string

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

403

Forbidden

application/json

Basic Error

Basic Error

object

message

string

documentation_url

string

url

string

status

string

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Validation failed, or the endpoint has been spammed.

application/json

Validation Error

Validation Error

object

message

required

string

documentation_url

required

string

errors

Array<object>

object

resource

string

field

string

message

string

code

required

string

index

integer

value

One of:

string

nullable

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}

Add a field to an organization-owned project.

Parameters

Path Parameters

Request Body required

Examples

Responses

201

Examples

304

401

Example generated

403

Example generated

422

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated