Skip to content
Pealboard

Create a portal

POST
/v1/portals
curl --request POST \
  --url https://api.pealboard.com/v1/portals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "slug": "acme", "description": "example", "requestPrefix": "example", "defaultRepositoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

The slug becomes a hostname, so the reserved list applies and it cannot be changed afterwards. The portal starts invite-only with private requests, which is the setting a workspace can safely leave alone while it decides.

defaultRepositoryId is where this portal’s request types send an issue when they name no repository of their own. Omit it and they fall back to the workspace’s default.

Access. Requires the admin role or above (admin, owner). A portal exposes the workspace’s work to people outside the company, so creating one is an administrative act. API-key scope: portals: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”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 80 characters
slug
required

Lowercase letters, digits and hyphens.

string
>= 2 characters <= 40 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
Example
acme
description
string
<= 500 characters
requestPrefix

Defaults to the first letters of the name.

string
/^[A-Z0-9]{2,6}$/
defaultRepositoryId

A synced repository of this workspace. Where this portal’s request types send an issue when they name none. Falls back to the workspace’s default.

string format: uuid

Responses

Section titled “Responses”

201

Section titled “201”

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
defaultRepository
required

Where a request type sends an issue when it names no repository of its own. The portal’s own default, or the workspace’s when the portal has none.

object
id
required

A UUID this API issued.

string format: uuid
fullName
required
string
inherited
required

True when this is the workspace’s default rather than the portal’s own. Clearing the portal’s default returns it to the workspace’s.

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",
  "defaultRepository": {
    "fullName": "mersoft-corp/issues"
  }
}

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