Skip to content
Pealboard

Comment on an issue

POST
/v1/issues/{issueId}/comments
curl --request POST \
  --url https://api.pealboard.com/v1/issues/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/comments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "body": "example", "visibility": "internal", "portalId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

visibility: "internal" posts an ordinary GitHub comment that no customer ever sees.

visibility: "public" is Reply to portal: the same GitHub comment with a hidden marker appended, and that marker is the only thing that makes it visible to customers of the named portal. Nothing typed into GitHub reaches a customer without it. A public comment needs portalId, because a marker names one portal and an issue can be shared to several.

Access. Requires the member role or above (member, admin, owner). Commenting writes to the customer’s GitHub repository under their installation. API-key scope: issues:write.

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

Retries. Send Idempotency-Key and a retry with the same key within 24 hours returns the first answer rather than acting twice.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
issueId
required

From GET /v1/issues.

string format: uuid

From GET /v1/issues.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
body
required
string
>= 1 characters <= 65536 characters
visibility

public means a customer of the named portal can see it. Every other comment is internal and never reaches a customer.

string
default: internal
Allowed values: internal public
portalId

Required when visibility is public. The portal whose customers will see it.

string format: uuid

Responses

Section titled “Responses”

201

Section titled “201”

The comment.

Media typeapplication/json
object
id
required

A UUID this API issued.

string format: uuid
nodeId
required
string
issueId
required

A UUID this API issued.

string format: uuid
body
required

What the person typed. The attribution footer and the marker are stripped here and kept on GitHub; sending an edited body back keeps them.

string
author
required
object
id
required

GitHub’s numeric user id.

number
login
required
string
avatarUrl
required
string | null format: uri
type
required

User, Bot or Organization.

string
authoredBy
required
object
membershipId
required

A UUID this API issued.

string | null format: uuid
name
required

The display name. Never an email address.

string
kind
required

team: a workspace member, the same word a portal uses for the same people. customer: a portal customer, whose request or comment the App wrote on their behalf; membershipId is null.

string
Allowed values: team customer
visibility
required

public means a customer of the named portal can see it. Every other comment is internal and never reaches a customer.

string
Allowed values: internal public
portalId
required

Set when the comment was written in a portal by a customer.

string | null format: uuid
htmlUrl
required
string format: uri
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "authoredBy": {
    "kind": "team"
  },
  "visibility": "internal"
}

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