Skip to content
forgit api docs

Add item to organization owned project

POST
/orgs/{org}/projectsV2/{project_number}/items

Add an issue or pull request item to the specified organization owned project.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

project_number
required
integer

The project’s number.

Request Body required

Section titled “ Request Body required ”

Details of the item to add to the project. You can specify either the unique ID or the repository owner, name, and issue/PR number.

Media type application/json
One of:
object
type

The type of item to add to the project. Must be either Issue or PullRequest.

string
Allowed values: Issue PullRequest
id
required

The unique identifier of the issue or pull request to add to the project.

integer
owner

The repository owner login.

string
repo

The repository name.

string
number

The issue or pull request number.

integer
Examples

Add an issue using its unique ID 

{
  "type": "Issue",
  "id": 3
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
Projects v2 Item

An item belonging to a project

object
id
required

The unique identifier of the project item.

number
node_id

The node ID of the project item.

string
content
One of:
Issue

Issues are a great way to keep track of tasks, enhancements, and bugs for your projects.

object
id
required
integer format: int64
node_id
required
string
url
required

URL for the issue

string format: uri
repository_url
required
string format: uri
labels_url
required
string
comments_url
required
string format: uri
events_url
required
string format: uri
html_url
required
string format: uri
number
required

Number uniquely identifying the issue within its repository

integer
state
required

State of the issue; either ‘open’ or ‘closed’

string
state_reason

The reason for the current state

string
nullable
Allowed values: completed reopened not_planned duplicate
title
required

Title of the issue

string
body

Contents of the issue

string
nullable
user
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
labels
required

Labels to associate with this issue; pass one or more label names to replace the set of labels on this issue; send an empty array to clear all labels from the issue; note that the labels are silently dropped for users without push access to the repository

Array
One of:
string
assignee
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
assignees
Array<object>
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
milestone
required
Milestone

A collection of related issues and pull requests.

object
url
required
string format: uri
html_url
required
string format: uri
labels_url
required
string format: uri
id
required
integer
node_id
required
string
number
required

The number of the milestone.

integer
state
required

The state of the milestone.

string
default: open
Allowed values: open closed
title
required

The title of the milestone.

string
description
required
string
nullable
creator
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
open_issues
required
integer
closed_issues
required
integer
created_at
required
string format: date-time
updated_at
required
string format: date-time
closed_at
required
string format: date-time
nullable
due_on
required
string format: date-time
nullable
locked
required
boolean
active_lock_reason
string
nullable
comments
required
integer
pull_request
object
merged_at
string format: date-time
nullable
diff_url
required
string format: uri
nullable
html_url
required
string format: uri
nullable
patch_url
required
string format: uri
nullable
url
required
string format: uri
nullable
closed_at
required
string format: date-time
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
draft
boolean
closed_by
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
body_html
string
body_text
string
timeline_url
string format: uri
type
Issue Type

The type assigned to the issue. This is only present for issues in repositories where issue types are supported.

object
id
required

The unique identifier of the issue type.

integer
node_id
required

The node identifier of the issue type.

string
name
required

The name of the issue type.

string
description
required

The description of the issue type.

string
nullable
color

The color of the issue type.

string
nullable
Allowed values: gray blue green yellow orange red pink purple
created_at

The time the issue type created.

string format: date-time
updated_at

The time the issue type last updated.

string format: date-time
is_enabled

The enabled state of the issue type.

boolean
repository
Repository

A repository on GitHub.

object
id
required

Unique identifier of the repository

integer format: int64
node_id
required
string
name
required

The name of the repository.

string
full_name
required
string
license
required
License Simple

License Simple

object
key
required
string
name
required
string
url
required
string format: uri
nullable
spdx_id
required
string
nullable
node_id
required
string
html_url
string format: uri
forks
required
integer
permissions
object
admin
required
boolean
pull
required
boolean
triage
boolean
push
required
boolean
maintain
boolean
owner
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
private
required

Whether the repository is private or public.

boolean
html_url
required
string format: uri
description
required
string
nullable
fork
required
boolean
url
required
string format: uri
archive_url
required
string
assignees_url
required
string
blobs_url
required
string
branches_url
required
string
collaborators_url
required
string
comments_url
required
string
commits_url
required
string
compare_url
required
string
contents_url
required
string
contributors_url
required
string format: uri
deployments_url
required
string format: uri
downloads_url
required
string format: uri
events_url
required
string format: uri
forks_url
required
string format: uri
git_commits_url
required
string
git_refs_url
required
string
git_tags_url
required
string
git_url
required
string
issue_comment_url
required
string
issue_events_url
required
string
issues_url
required
string
keys_url
required
string
labels_url
required
string
languages_url
required
string format: uri
merges_url
required
string format: uri
milestones_url
required
string
notifications_url
required
string
pulls_url
required
string
releases_url
required
string
ssh_url
required
string
stargazers_url
required
string format: uri
statuses_url
required
string
subscribers_url
required
string format: uri
subscription_url
required
string format: uri
tags_url
required
string format: uri
teams_url
required
string format: uri
trees_url
required
string
clone_url
required
string
mirror_url
required
string format: uri
nullable
hooks_url
required
string format: uri
svn_url
required
string format: uri
homepage
required
string format: uri
nullable
language
required
string
nullable
forks_count
required
integer
stargazers_count
required
integer
watchers_count
required
integer
size
required

The size of the repository, in kilobytes. Size is calculated hourly. When a repository is initially created, the size is 0.

integer
default_branch
required

The default branch of the repository.

string
open_issues_count
required
integer
is_template

Whether this repository acts as a template that can be used to generate new repositories.

boolean
topics
Array<string>
has_issues
required

Whether issues are enabled.

boolean
default: true
has_projects
required

Whether projects are enabled.

boolean
default: true
has_wiki
required

Whether the wiki is enabled.

boolean
default: true
has_pages
required
boolean
has_downloads
required

Whether downloads are enabled.

boolean
default: true
has_discussions

Whether discussions are enabled.

boolean
has_pull_requests

Whether pull requests are enabled.

boolean
default: true
pull_request_creation_policy

The policy controlling who can create pull requests: all or collaborators_only.

string
Allowed values: all collaborators_only
archived
required

Whether the repository is archived.

boolean
disabled
required

Returns whether or not this repository disabled.

boolean
visibility

The repository visibility: public, private, or internal.

string
default: public
pushed_at
required
string format: date-time
nullable
created_at
required
string format: date-time
nullable
updated_at
required
string format: date-time
nullable
allow_rebase_merge

Whether to allow rebase merges for pull requests.

boolean
default: true
temp_clone_token
string
allow_squash_merge

Whether to allow squash merges for pull requests.

boolean
default: true
allow_auto_merge

Whether to allow Auto-merge to be used on pull requests.

boolean
delete_branch_on_merge

Whether to delete head branches when pull requests are merged

boolean
allow_update_branch

Whether or not a pull request head branch that is behind its base branch can always be updated even if it is not required to be up to date before merging.

boolean
use_squash_pr_title_as_default

Whether a squash merge commit can use the pull request title as default. **This property is closing down. Please use squash_merge_commit_title instead.

boolean
squash_merge_commit_title

The default value for a squash merge commit title:

  • PR_TITLE - default to the pull request’s title.
  • COMMIT_OR_PR_TITLE - default to the commit’s title (if only one commit) or the pull request’s title (when more than one commit).
string
Allowed values: PR_TITLE COMMIT_OR_PR_TITLE
squash_merge_commit_message

The default value for a squash merge commit message:

  • PR_BODY - default to the pull request’s body.
  • COMMIT_MESSAGES - default to the branch’s commit messages.
  • BLANK - default to a blank commit message.
string
Allowed values: PR_BODY COMMIT_MESSAGES BLANK
merge_commit_title

The default value for a merge commit title.

  • PR_TITLE - default to the pull request’s title.
  • MERGE_MESSAGE - default to the classic title for a merge message (e.g., Merge pull request #123 from branch-name).
string
Allowed values: PR_TITLE MERGE_MESSAGE
merge_commit_message

The default value for a merge commit message.

  • PR_TITLE - default to the pull request’s title.
  • PR_BODY - default to the pull request’s body.
  • BLANK - default to a blank commit message.
string
Allowed values: PR_BODY PR_TITLE BLANK
allow_merge_commit

Whether to allow merge commits for pull requests.

boolean
default: true
allow_forking

Whether to allow forking this repo

boolean
web_commit_signoff_required

Whether to require contributors to sign off on web-based commits

boolean
open_issues
required
integer
watchers
required
integer
master_branch
string
starred_at
string
anonymous_access_enabled

Whether anonymous git access is enabled for this repository

boolean
code_search_index_status

The status of the code search index for this repository

object
lexical_search_ok
boolean
lexical_commit_sha
string
performed_via_github_app
GitHub app

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

object
id
required

Unique identifier of the GitHub app

integer
slug

The slug name of the GitHub app

string
node_id
required
string
client_id
string
owner
required
One of:
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
name
required

The name of the GitHub app

string
description
required
string
nullable
external_url
required
string format: uri
html_url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
permissions
required

The set of permissions for the GitHub app

object
issues
string
checks
string
metadata
string
contents
string
deployments
string
key
additional properties
string
events
required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>
installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer
author_association
author_association

How the author is associated with the repository.

string
Allowed values: COLLABORATOR CONTRIBUTOR FIRST_TIMER FIRST_TIME_CONTRIBUTOR MANNEQUIN MEMBER NONE OWNER
reactions
Reaction Rollup
object
url
required
string format: uri
total_count
required
integer
+1
required
integer
-1
required
integer
laugh
required
integer
confused
required
integer
heart
required
integer
hooray
required
integer
eyes
required
integer
rocket
required
integer
sub_issues_summary
Sub-issues Summary
object
total
required
integer
completed
required
integer
percent_completed
required
integer
parent_issue_url

URL to get the parent issue of this issue, if it is a sub-issue

string format: uri
nullable
pinned_comment
Issue Comment

Comments provide a way for people to collaborate on an issue.

object
id
required

Unique identifier of the issue comment

integer format: int64
node_id
required
string
url
required

URL for the issue comment

string format: uri
body

Contents of the issue comment

string
body_text
string
body_html
string
html_url
required
string format: uri
user
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
issue_url
required
string format: uri
author_association
author_association

How the author is associated with the repository.

string
Allowed values: COLLABORATOR CONTRIBUTOR FIRST_TIMER FIRST_TIME_CONTRIBUTOR MANNEQUIN MEMBER NONE OWNER
performed_via_github_app
GitHub app

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

object
id
required

Unique identifier of the GitHub app

integer
slug

The slug name of the GitHub app

string
node_id
required
string
client_id
string
owner
required
One of:
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
name
required

The name of the GitHub app

string
description
required
string
nullable
external_url
required
string format: uri
html_url
required
string format: uri
created_at
required
string format: date-time
updated_at
required
string format: date-time
permissions
required

The set of permissions for the GitHub app

object
issues
string
checks
string
metadata
string
contents
string
deployments
string
key
additional properties
string
events
required

The list of events for the GitHub app. Note that the installation_target, security_advisory, and meta events are not included because they are global events and not specific to an installation.

Array<string>
installations_count

The number of installations associated with the GitHub app. Only returned when the integration is requesting details about itself.

integer
reactions
Reaction Rollup
object
url
required
string format: uri
total_count
required
integer
+1
required
integer
-1
required
integer
laugh
required
integer
confused
required
integer
heart
required
integer
hooray
required
integer
eyes
required
integer
rocket
required
integer
pin
Pinned Issue Comment

Context around who pinned an issue comment and when it was pinned.

object
pinned_at
required
string format: date-time
pinned_by
required
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
minimized
Minimized Issue Comment

Details about why an issue comment was minimized.

object
reason
required

The reason the comment was minimized.

string
nullable
issue_dependencies_summary
Issue Dependencies Summary
object
blocked_by
required
integer
blocking
required
integer
total_blocked_by
required
integer
total_blocking
required
integer
issue_field_values
Array<object>
Issue Field Value

A value assigned to an issue field

object
issue_field_id
required

Unique identifier for the issue field.

integer format: int64
issue_field_name

The human-readable name of the issue field.

string
node_id
required
string
data_type
required

The data type of the issue field

string
Allowed values: text single_select multi_select number date
value
required
Any of:
string
single_select_option

Details about the selected option (only present for single_select fields)

object
id
required

Unique identifier for the option.

integer format: int64
name
required

The name of the option

string
color
required

The color of the option

string
multi_select_options

Details about the selected options

Array<object>
nullable
object
id
required

Unique identifier for the option.

integer format: int64
name
required

The name of the option

string
color
required

The color of the option

string
content_type
required
Projects v2 Item Content Type

The type of content tracked in a project item

string
Allowed values: Issue PullRequest DraftIssue
creator
Simple User

A GitHub user.

object
name
string
nullable
email
string
nullable
login
required
string
id
required
integer format: int64
node_id
required
string
avatar_url
required
string format: uri
gravatar_id
required
string
nullable
url
required
string format: uri
html_url
required
string format: uri
followers_url
required
string format: uri
following_url
required
string
gists_url
required
string
starred_url
required
string
subscriptions_url
required
string format: uri
organizations_url
required
string format: uri
repos_url
required
string format: uri
events_url
required
string
received_events_url
required
string format: uri
type
required
string
site_admin
required
boolean
starred_at
string
user_view_type
string
created_at
required

The time when the item was created.

string format: date-time
updated_at
required

The time when the item was last updated.

string format: date-time
archived_at
required

The time when the item was archived.

string format: date-time
nullable
project_url

The URL of the project this item belongs to.

string format: uri
item_url

The URL of the item in the project.

string format: uri
Examples

Response for adding an issue using its unique ID 

{
  "value": {
    "id": 17,
    "node_id": "PVTI_lADOANN5s84ACbL0zgBueEI",
    "content": {
      "id": 38,
      "node_id": "I_kwDOANN5s85FtLts",
      "title": "Example Draft Issue",
      "body": "This is a draft issue in the project.",
      "created_at": "2022-04-28T12:00:00Z",
      "updated_at": "2022-04-28T12:00:00Z",
      "user": {
        "login": "octocat",
        "id": 1,
        "node_id": "MDQ6VXNlcjE=",
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "gravatar_id": "",
        "url": "https://api.github.com/users/octocat",
        "html_url": "https://github.com/octocat",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "type": "User",
        "site_admin": false
      }
    },
    "content_type": "DraftIssue",
    "creator": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "created_at": "2022-04-28T12:00:00Z",
    "updated_at": "2022-04-28T12:00:00Z",
    "archived_at": null,
    "project_url": "https://api.github.com/users/octocat/projectsV2/1",
    "item_url": "https://api.github.com/users/octocat/projectsV2/items/17"
  }
}

304

Section titled “ 304 ”

Not modified

401

Section titled “ 401 ”

Requires authentication

Media type 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

Section titled “ 403 ”

Forbidden

Media type 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"
}