Skip to content
Pealboard

Change a portal

PATCH
/v1/portals/{portalId}
curl --request PATCH \
  --url https://api.pealboard.com/v1/portals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "branding": { "logoAttachmentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "accentColor": "example", "welcomeText": "example" }, "accessMode": "invite_only", "allowedDomains": [ "example" ], "defaultVisibility": "private", "shareGithubComments": true, "notifyStatusChange": true, "notifyPublicComment": true }'

The slug cannot be changed: it is a hostname, and every link a customer has bookmarked and every marker in a GitHub issue body carries it. Turning on shareGithubComments makes every comment on every shared issue visible to this portal’s customers, including ones written before it was turned on.

Access. Requires the admin role or above (admin, owner). Access mode, default visibility and comment sharing decide what people outside the company can read. API-key scope: portals:write.

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
name
string
>= 1 characters <= 80 characters
description
string | null
<= 500 characters
branding
object
logoAttachmentId

A UUID this API issued.

string | null format: uuid
accentColor
string | null
/^#[0-9a-fA-F]{6}$/
welcomeText
string | null
<= 2000 characters
accessMode

Invite_only: a member adds each customer, and an unknown address is refused before a code is sent. domain_allowlist: anyone whose verified email domain is listed joins the company that domain is mapped to. open: anyone may sign in, and a new customer’s first request waits in the hold queue.

string
Allowed values: invite_only domain_allowlist open
allowedDomains
Array<string>
<= 50 items
defaultVisibility

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
shareGithubComments
boolean
notifyStatusChange
boolean
notifyPublicComment
boolean

Responses

Section titled “Responses”

200

Section titled “200”

The portal.

Media typeapplication/json
object
id
required

A UUID this API issued.

string format: uuid
slug
required

Lowercase letters, digits and hyphens.

string
>= 2 characters <= 40 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
name
required
string
description
required
string | null
url
required

Where customers reach this portal.

string format: uri
requestPrefix
required

The ACME in ACME-42.

string
branding
required
object
logoAttachmentId
required

An attachment uploaded with POST /v1/attachments. Rendered through a signed URL.

string | null format: uuid
logoUrl
required

A signed link to the logo, good for 30 days. Read only.

string | null format: uri
accentColor
required
string | null
/^#[0-9a-fA-F]{6}$/
welcomeText
required
string | null
<= 2000 characters
accessMode
required

Invite_only: a member adds each customer, and an unknown address is refused before a code is sent. domain_allowlist: anyone whose verified email domain is listed joins the company that domain is mapped to. open: anyone may sign in, and a new customer’s first request waits in the hold queue.

string
Allowed values: invite_only domain_allowlist open
allowedDomains
required
Array<string>
defaultVisibility
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
shareGithubComments
required

When on, every comment on a shared issue is visible to this portal’s customers, including ones written before the setting was turned on. Off by default.

boolean
notifyStatusChange
required
boolean
notifyPublicComment
required
boolean
counts
required
object
requestTypes
required
integer
companies
required
integer
customers
required
integer
requests
required
integer
held
required
integer
createdAt
required
string format: date-time
Example
{
  "slug": "acme",
  "accessMode": "invite_only",
  "defaultVisibility": "private"
}

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

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