Skip to content
Pealboard

Share an issue to a portal

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

Links an existing issue to this portal as a request. Nothing is duplicated and nothing is written to GitHub: the issue is the same object, and removing it from the portal later leaves it untouched. One issue maps to at most one request per portal.

Access. Requires the member role or above (member, admin, owner). Sharing an issue to a portal shows work the team already did to the customer who asked for it, which is ordinary member work. API-key scope: requests: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”
portalId
required

From GET /v1/portals.

string format: uuid

From GET /v1/portals.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
issueId
required

A UUID this API issued.

string format: uuid
companyId

A UUID this API issued.

string | null format: uuid
visibility

Defaults to the portal’s own default visibility.

string
Allowed values: private company public
requestTypeId

Only for its status rules. No form is filled in and no destination is used.

string | null format: uuid

Responses

Section titled “Responses”

201

Section titled “201”

The request.

Media typeapplication/json
object
id
required

A UUID this API issued.

string format: uuid
reference
required

ACME-42.

string
number
required
integer
title
required
string
status
required

Derived from the issue at read time, never stored.

object
id
required

The stable identifier a client filters on. The word is in status.label.

string
Allowed values: open planned in_progress waiting_on_you completed merged closed
label
required

The customer-facing word. Seven, fixed, and never GitHub’s own vocabulary.

string
Allowed values: Open Planned In progress Waiting on you Completed Merged Closed
visibility
required

Private: the requester and the workspace. company: everyone in the requester’s company. public: everyone in the portal. A manager sees every request in their company whatever this says.

string
Allowed values: private company public
issue
required

Null while the request is in the hold queue: it has not reached GitHub.

object
id
required

A UUID this API issued.

string format: uuid
number
required
integer
htmlUrl
required
string format: uri
state
required
string
Allowed values: open closed
requestType
required
object
id
required

A UUID this API issued.

string format: uuid
name
required
string
requester
required

The customer who submitted it. Null when a member shared an existing issue (see sharedBy), and null once the customer who submitted it has deleted their account.

object
id
required

A UUID this API issued.

string format: uuid
name
required
string
email
required
string format: email
sharedBy
required

The member who shared an existing issue to the portal. Null for a request a customer submitted.

object
membershipId
required

A UUID this API issued.

string format: uuid
name
required
string
company
required
object
id
required

A UUID this API issued.

string format: uuid
name
required
string
voteCount
required
integer
held
required
boolean
submission
required

The answers as they were submitted, in the request type’s form order, while the request is held. Null once it has an issue: the issue body is the record then, and GET /v1/issues/{issueId} has it.

Array<object> | null
object
key
required
string
label
required

The form field’s label, or its key when the form no longer has the field.

string
type
required

Text is one line and textarea is many. select needs options; every other type ignores them.

string
Allowed values: text textarea select checkbox email url number date
value
required
Any of:
string
rejectedAt
required
string | null format: date-time
url
required

The request in its portal.

string format: uri
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "reference": "ACME-42",
  "status": {
    "id": "open",
    "label": "Open"
  },
  "visibility": "private",
  "issue": {
    "state": "open"
  },
  "submission": [
    {
      "type": "text"
    }
  ]
}

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