Skip to content
Pealboard

Edit a project

PATCH
/v1/projects/{projectId}
curl --request PATCH \
  --url https://api.pealboard.com/v1/projects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "shortDescription": "example", "public": true }'

Only the fields sent are changed. A description can be changed but not removed — GitHub takes a blank one, keeps what it had and answers success, so Pealboard refuses it rather than reporting a write that did not happen. Remove it in the project’s own settings on GitHub.

The Status options are not editable here. GitHub replaces the whole option set and issues new ids, so renaming one after cards are on it is a decision about the cards — and that is GitHub’s own board to make it on.

public is refused with 403 whenever Pealboard is writing as the App, which is every organization installation: GitHub does not let an App change a project’s visibility. A value that matches what the project already is changes nothing and is accepted.

On a personal account, editing is refused with 403 too, before anything reaches GitHub: neither the App nor your own linked GitHub account can change a project there, for the same reason neither can create one. Edit it on GitHub directly; Pealboard picks up the change on the next sync.

Access. Requires the member role or above (member, admin, owner). Renaming a project renames the customer’s GitHub project. API-key scope: projects:write.

Billing. Refused with 402 while the workspace’s billing has lapsed. Reads continue and nothing is deleted.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
projectId
required

From GET /v1/projects.

string format: uuid

From GET /v1/projects.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
title
string
>= 1 characters <= 256 characters
shortDescription

Changed, never emptied: GitHub accepts a blank description, keeps the old one and reports success, so a blank one is refused here.

string
>= 1 characters <= 1024 characters
public
boolean
Examplegenerated
{
  "title": "example",
  "shortDescription": "example",
  "public": true
}

Responses

Section titled “Responses”

200

Section titled “200”

The project.

Media typeapplication/json
object
id
required

A UUID this API issued.

string format: uuid
nodeId
required
string
number
required
number
title
required
string
shortDescription
required
string | null
ownerLogin
required
string
public
required
boolean
closed
required
boolean
url
required

The project on GitHub.

string format: uri
fields
required
Array<object>
object
id
required

A UUID this API issued.

string format: uuid
nodeId
required

What every field value is keyed by. Survives a rename.

string
name
required
string
dataType
required

GitHub’s ProjectV2FieldType: TEXT, SINGLE_SELECT, NUMBER, DATE, ITERATION, and the rest.

string
options
required

In the order the project shows them. Null unless the field is a single select.

Array<object> | null
object
id
required
string
name
required
string
color
required
string
description
required
string
isIssueField
required

True when the field is an organization issue field linked into this project.

boolean
itemCount
required
number
syncedAt
required
string format: date-time
Examplegenerated
{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "nodeId": "example",
  "number": 1,
  "title": "example",
  "shortDescription": "example",
  "ownerLogin": "example",
  "public": true,
  "closed": true,
  "url": "https://example.com",
  "fields": [
    {
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "nodeId": "example",
      "name": "example",
      "dataType": "example",
      "options": [
        {
          "id": "example",
          "name": "example",
          "color": "example",
          "description": "example"
        }
      ],
      "isIssueField": true
    }
  ],
  "itemCount": 1,
  "syncedAt": "2026-04-15T12:00:00Z"
}

401

Section titled “401”

No valid credentials.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

402

Section titled “402”

The workspace’s billing has lapsed, so writes are refused.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

403

Section titled “403”

Authenticated, but not permitted.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

404

Section titled “404”

No such resource, or it is not visible to you.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

409

Section titled “409”

The request conflicts with the current state.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

422

Section titled “422”

The request did not match the expected shape.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

429

Section titled “429”

Rate limited. Retry after the interval in the header.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

502

Section titled “502”

GitHub or another dependency refused or did not answer. Nothing in the workspace changed.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}