GitHub: Projects schemas

← Projects operations · All schemas

Add field to user owned project — request body — body / data_type: iteration iteration configuration

Field	Type	Presence	Description and constraints
$	object	Root	The configuration for iteration fields.
duration	integer	Required within parent	The default duration for iterations in days. Individual iterations can override this value.
iterations	array	Optional	Zero or more iterations for the field.
iterations[]	object	Each item	Additional keys: not allowed
iterations[].duration	integer	Required within parent	The duration of the iteration in days.
iterations[].start_date	string	Required within parent	The start date of the iteration. Format: date
iterations[].title	string	Required within parent	The title of the iteration.
start_date	string	Required within parent	The start date of the first iteration. Format: date

Add field to user owned project — request body — body / data_type: single select

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
data_type	string	Required within parent	The field's data type. One of: single_select
name	string	Required within parent	The name of the field.
single_select_options	array	Required within parent	The options available for single select fields. At least one option must be provided when creating a single select field.
single_select_options[]	Model	Each item	Expand Add field to user owned project — request body — body / data_type: single select single select options item

Referenced models: Add field to user owned project — request body — body / data_type: single select single select options item

Add field to user owned project — request body — body / data_type: single select single select options item

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
color	string	Optional	The color associated with the option. One of: BLUE, GRAY, GREEN, ORANGE, PINK, PURPLE, RED, YELLOW
description	string	Optional	The description of the option.
name	string	Optional	The display name of the option.

Add item to user owned project — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
id	integer	Optional	The unique identifier of the issue or pull request to add to the project.
number	integer	Optional	The issue or pull request number.
owner	string	Optional	The repository owner login.
repo	string	Optional	The repository name.
type	string	Required within parent	The type of item to add to the project. Must be either Issue or PullRequest. One of: Issue, PullRequest
$ (oneOf 1)	JSON	Alternative
$ (oneOf 2)	JSON	Alternative

Add item to user owned project — response body

Field	Type	Presence	Description and constraints
$	object	Root	An item belonging to a project
archived_at	JSON	Required within parent
archived_at (anyOf 1)	string	Alternative	The time when the item was archived. Format: date-time
archived_at (anyOf 2)	null	Alternative
content	JSON	Optional	The content represented by the item.
content (anyOf 1)	Model	Alternative	Expand Get an issue — response body
content (anyOf 2)	Model	Alternative	Expand Request reviewers for a pull request — response body
content (anyOf 3)	Model	Alternative	Expand Add item to user owned project — response body — content Draft Issue
content_type	string	Required within parent	The type of content tracked in a project item Known values: Issue, PullRequest, DraftIssue
created_at	string	Required within parent	The time when the item was created. Format: date-time
creator	Model	Optional	Expand List users — response body — item
id	JSON	Required within parent
id (anyOf 1)	number	Alternative	The unique identifier of the project item.
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
item_url	string	Optional	The URL of the item in the project. Format: uri
node_id	string	Optional	The node ID of the project item.
project_url	string	Optional	The URL of the project this item belongs to. Format: uri
updated_at	string	Required within parent	The time when the item was last updated. Format: date-time

Referenced models: Get an issue — response body, Add item to user owned project — response body — content Draft Issue, Request reviewers for a pull request — response body, List users — response body — item

Add item to user owned project — response body — content Draft Issue

Field	Type	Presence	Description and constraints
$	object	Root	A draft issue in a project
body	JSON	Optional
body (anyOf 1)	string	Alternative	The body content of the draft issue
body (anyOf 2)	null	Alternative
created_at	string	Required within parent	The time the draft issue was created Format: date-time
id	JSON	Required within parent
id (anyOf 1)	number	Alternative	The ID of the draft issue
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
node_id	string	Required within parent	The node ID of the draft issue
title	string	Required within parent	The title of the draft issue
updated_at	string	Required within parent	The time the draft issue was last updated Format: date-time
user	Model	Required within parent	Expand Get an issue — response body — user

Referenced models: Get an issue — response body — user

Create a view for a user-owned project — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
filter	string	Optional	The filter query for the view. See [Filtering projects](https://docs.github.com/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects) for more information.
group_by	array	Optional	The field IDs to group items by (horizontal grouping). Supports a single field. The field must support grouping; fields such as `Title`, `Reviewers`, `Linked pull requests`, `Sub-issues progress`, `Tracked by`, and `Tracks` cannot be grouped on. Maximum items: 1
group_by[]	integer	Each item
layout	string	Required within parent	The layout of the view. One of: table, board, roadmap
name	string	Required within parent	The name of the view.
sort_by	array	Optional	Sorting configuration for the view. Each element is a two-element array of `[field_id, direction]` where `direction` is `"asc"` or `"desc"`. Supports multiple sort criteria applied in order.
sort_by[]	array	Each item	Maximum items: 2 Minimum items: 2
sort_by[][]	JSON	Each item
sort_by[][] (oneOf 1)	integer	Alternative
sort_by[][] (oneOf 2)	string	Alternative
vertical_group_by	array	Optional	The field IDs to use as columns in `board` layout (vertical grouping). Supports a single field. The field must support grouping; fields such as `Title`, `Reviewers`, `Linked pull requests`, `Sub-issues progress`, `Tracked by`, and `Tracks` cannot be grouped on. Maximum items: 1
vertical_group_by[]	integer	Each item
visible_fields	array	Optional	`visible_fields` is not applicable to `roadmap` layout views. For `table` and `board` layouts, this represents the field IDs that should be visible in the view. If not provided, the default visible fields will be used.
visible_fields[]	integer	Each item

Create a view for a user-owned project — response body

Field	Type	Presence	Description and constraints
$	object	Root	A view inside a projects v2 project
created_at	string	Required within parent	The time when the view was created. Format: date-time
creator	JSON	Required within parent
creator (allOf 1)	Model	All variants apply	Expand List users — response body — item
filter	JSON	Optional
filter (anyOf 1)	string	Alternative	The filter query for the view.
filter (anyOf 2)	null	Alternative
group_by	array	Required within parent	The list of field IDs used for horizontal grouping.
group_by[]	JSON	Each item
group_by[] (anyOf 1)	integer	Alternative
group_by[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
html_url	string	Required within parent	The web URL of the view. Format: uri
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	The unique identifier of the view.
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
layout	string	Required within parent	The layout of the view. Known values: table, board, roadmap
name	string	Required within parent	The name of the view.
node_id	string	Required within parent	The node ID of the view.
number	JSON	Required within parent
number (anyOf 1)	integer	Alternative	The number of the view within the project.
number (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
project_url	string	Required within parent	The API URL of the project that contains the view.
sort_by	array	Required within parent	The sorting configuration for the view. Each element is a tuple of [field_id, direction] where direction is "asc" or "desc".
sort_by[]	array	Each item	Maximum items: 2 Minimum items: 2
sort_by[][]	JSON	Each item
sort_by[][] (anyOf 1)	JSON	Alternative
sort_by[][] (anyOf 1) (anyOf 1)	integer	Alternative
sort_by[][] (anyOf 1) (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
sort_by[][] (anyOf 2)	string	Alternative
updated_at	string	Required within parent	The time when the view was last updated. Format: date-time
vertical_group_by	array	Required within parent	The list of field IDs used for vertical grouping (board layout).
vertical_group_by[]	JSON	Each item
vertical_group_by[] (anyOf 1)	integer	Alternative
vertical_group_by[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
visible_fields	array	Required within parent	The list of field IDs that are visible in the view.
visible_fields[]	JSON	Each item
visible_fields[] (anyOf 1)	integer	Alternative
visible_fields[] (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: List users — response body — item

Get project field for user — response body

Field	Type	Presence	Description and constraints
$	object	Root	A field inside a projects v2 project
configuration	object	Optional	Configuration for iteration fields.
configuration.duration	JSON	Optional
configuration.duration (anyOf 1)	integer	Alternative	The duration of the iteration in days.
configuration.duration (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
configuration.iterations	array	Optional
configuration.iterations[]	Model	Each item	Expand Get project field for user — response body — configuration iterations item
configuration.start_day	JSON	Optional
configuration.start_day (anyOf 1)	integer	Alternative	The day of the week when the iteration starts.
configuration.start_day (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
created_at	string	Required within parent	The time when the field was created. Format: date-time
data_type	string	Required within parent	The field's data type. Known values: assignees, linked_pull_requests, reviewers, labels, milestone, repository, title, text, single_select, number, date, iteration, issue_type, parent_issue, sub_issues_progress
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	The unique identifier of the field.
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
issue_field_id	JSON	Optional
issue_field_id (anyOf 1)	integer	Alternative	The ID of the issue field.
issue_field_id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Required within parent	The name of the field.
node_id	string	Optional	The node ID of the field.
options	array	Optional	The options available for single select fields.
options[]	Model	Each item	Expand Get project field for user — response body — options item
project_url	string	Required within parent	The API URL of the project that contains the field.
updated_at	string	Required within parent	The time when the field was last updated. Format: date-time

Referenced models: Get project field for user — response body — configuration iterations item, Get project field for user — response body — options item

Get project field for user — response body — configuration iterations item

Field	Type	Presence	Description and constraints
$	object	Root	An iteration setting for an iteration field
completed	boolean	Required within parent	Whether the iteration has been completed.
duration	JSON	Required within parent
duration (anyOf 1)	integer	Alternative	The duration of the iteration in days.
duration (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
id	string	Required within parent	The unique identifier of the iteration setting.
start_date	string	Required within parent	The start date of the iteration. Format: date
title	object	Required within parent	The iteration title, in raw text and HTML formats.
title.html	string	Required within parent
title.raw	string	Required within parent

Get project field for user — response body — options item

Field	Type	Presence	Description and constraints
$	object	Root	An option for a single select field
color	string	Required within parent	The color associated with the option.
description	object	Required within parent	The description of the option, in raw text and HTML formats.
description.html	string	Required within parent
description.raw	string	Required within parent
id	string	Required within parent	The unique identifier of the option.
name	object	Required within parent	The display name of the option, in raw text and HTML formats.
name.html	string	Required within parent
name.raw	string	Required within parent

Get project for user — response body

Field	Type	Presence	Description and constraints
$	object	Root	A projects v2 project
closed_at	JSON	Required within parent
closed_at (anyOf 1)	string	Alternative	The time when the project was closed. Format: date-time
closed_at (anyOf 2)	null	Alternative
created_at	string	Required within parent	The time when the project was created. Format: date-time
creator	Model	Required within parent	Expand List users — response body — item
deleted_at	JSON	Required within parent
deleted_at (anyOf 1)	string	Alternative	The time when the project was deleted. Format: date-time
deleted_at (anyOf 2)	null	Alternative
deleted_by	Model	Required within parent	Expand Get an issue — response body — user
description	JSON	Required within parent
description (anyOf 1)	string	Alternative	A short description of the project.
description (anyOf 2)	null	Alternative
id	JSON	Required within parent
id (anyOf 1)	number	Alternative	The unique identifier of the project.
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
is_template	boolean	Optional	Whether this project is a template
latest_status_update	Model	Optional	Expand Get project for user — response body — latest status update
node_id	string	Required within parent	The node ID of the project.
number	JSON	Required within parent
number (anyOf 1)	integer	Alternative	The project number.
number (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
owner	Model	Required within parent	Expand List users — response body — item
public	boolean	Required within parent	Whether the project is visible to anyone with access to the owner.
short_description	JSON	Required within parent
short_description (anyOf 1)	string	Alternative	A concise summary of the project.
short_description (anyOf 2)	null	Alternative
state	string	Optional	The current state of the project. Known values: open, closed
title	string	Required within parent	The project title.
updated_at	string	Required within parent	The time when the project was last updated. Format: date-time

Referenced models: Get project for user — response body — latest status update, Get an issue — response body — user, List users — response body — item

Get project for user — response body — latest status update

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	object	Alternative	An status update belonging to a project
$ (anyOf 1).body	JSON	Optional
$ (anyOf 1).body (anyOf 1)	string	Alternative	Body of the status update
$ (anyOf 1).body (anyOf 2)	null	Alternative
$ (anyOf 1).created_at	string	Required within parent	The time when the status update was created. Format: date-time
$ (anyOf 1).creator	Model	Optional	Expand List users — response body — item
$ (anyOf 1).id	JSON	Required within parent
$ (anyOf 1).id (anyOf 1)	number	Alternative	The unique identifier of the status update.
$ (anyOf 1).id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 1).node_id	string	Required within parent	The node ID of the status update.
$ (anyOf 1).project_node_id	string	Optional	The node ID of the project that this status update belongs to.
$ (anyOf 1).start_date	string	Optional	The start date of the period covered by the update. Format: date
$ (anyOf 1).status	JSON	Optional
$ (anyOf 1).status (anyOf 1)	string	Alternative	The current status. Known values: INACTIVE, ON_TRACK, AT_RISK, OFF_TRACK, COMPLETE
$ (anyOf 1).status (anyOf 2)	null	Alternative
$ (anyOf 1).target_date	string	Optional	The target date associated with the update. Format: date
$ (anyOf 1).updated_at	string	Required within parent	The time when the status update was last updated. Format: date-time
$ (anyOf 2)	null	Alternative

Referenced models: List users — response body — item

Update project item for user — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
fields	array	Required within parent	A list of field updates to apply.
fields[]	object	Each item
fields[].id	integer	Required within parent	The ID of the project field to update.
fields[].value	JSON	Required within parent
fields[].value (anyOf 1)	JSON	Alternative	The new value for the field: - For text, number, and date fields, provide the new value directly. - For single select and iteration fields, provide the ID of the option or iteration. - To clear the field, set this to null.
fields[].value (anyOf 1) (oneOf 1)	string	Alternative
fields[].value (anyOf 1) (oneOf 2)	number	Alternative
fields[].value (anyOf 2)	null	Alternative

Update project item for user — response body

Field	Type	Presence	Description and constraints
$	object	Root	An item belonging to a project
archived_at	JSON	Required within parent
archived_at (anyOf 1)	string	Alternative	The time when the item was archived. Format: date-time
archived_at (anyOf 2)	null	Alternative
content	JSON	Optional
content (anyOf 1)	object	Alternative	The content of the item, which varies by content type. Additional keys: allowed
content (anyOf 2)	null	Alternative
content_type	string	Required within parent	The type of content tracked in a project item Known values: Issue, PullRequest, DraftIssue
created_at	string	Required within parent	The time when the item was created. Format: date-time
creator	Model	Optional	Expand List users — response body — item
fields	array	Optional	The fields and values associated with this item.
fields[]	object	Each item	Additional keys: allowed
id	JSON	Required within parent
id (anyOf 1)	number	Alternative	The unique identifier of the project item.
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
item_url	JSON	Optional
item_url (anyOf 1)	string	Alternative	The API URL of this item. Format: uri
item_url (anyOf 2)	null	Alternative
node_id	string	Optional	The node ID of the project item.
project_url	string	Optional	The API URL of the project that contains this item. Format: uri
updated_at	string	Required within parent	The time when the item was last updated. Format: date-time

Referenced models: List users — response body — item