Create a request type

POST

/v1/portals/{portalId}/request-types

const url = 'https://api.pealboard.com/v1/portals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/request-types';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","description":"example","form":[{"key":"example","label":"example","type":"text","required":false,"options":["example"],"helpText":"example"}],"destination":{"repositoryId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","labels":[],"projectNodeId":"example","initialFieldValues":{},"issueType":"example"},"statusMap":[],"position":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.pealboard.com/v1/portals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/request-types \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "form": [ { "key": "example", "label": "example", "type": "text", "required": false, "options": [ "example" ], "helpText": "example" } ], "destination": { "repositoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "labels": [], "projectNodeId": "example", "initialFieldValues": {}, "issueType": "example" }, "statusMap": [], "position": 1 }'

The form is what a customer fills in; the destination is where the issue goes. statusMap overrides the default status rules for requests of this type — leave it empty to use the defaults, which cover closed, project Status and the needs-info label.

destination.repositoryId is optional. Omitted, it is the portal’s default repository, and then the workspace’s. The repository is resolved once, here, and stored on the request type: changing a default later does not move a request type that was already created.

Access. Requires the admin role or above (admin, owner). A request type decides which repository a stranger’s submission lands in, which is a decision about the workspace’s GitHub account. 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

bearerAuth

Parameters

Path Parameters

portalId

required

From GET /v1/portals.

string format: uuid

From GET /v1/portals.

Request Body

application/json

object

name

required

string

>= 1 characters <= 80 characters

description

string | null

<= 500 characters

form

Array<object>

<= 30 items

object

key

required

The key a submission sends this field’s value under.

string

>= 1 characters <= 60 characters /^[a-z0-9_]+$/

label

required

The heading this field becomes in the issue body.

string

>= 1 characters <= 120 characters

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

required

boolean

options

Array<string>

<= 50 items

helpText

string

<= 300 characters

destination

required

object

repositoryId

Where the issue is created. Omit it, or send null, and the portal’s default repository is used, and then the workspace’s; a request type with neither is refused with 422. The repository is resolved when the request type is saved and stored on it, so a request type already created keeps the repository it has whatever the defaults change to. On PATCH, null asks for that resolution again, now.

string | null format: uuid

labels

Array<string>

default: <= 20 items

projectNodeId

string | null

>= 1 characters

initialFieldValues

object

key

additional properties

issueType

string | null

>= 1 characters

statusMap

Array<object>

default: <= 30 items

First match wins, in the order given. An empty list means the default rules in ADR 0009.

object

when

required

One of:

object

kind

required

string

Allowed values: closed

stateReason

required

string | null

Allowed values: completed not_planned duplicate

status

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

position

Where in the chooser this request type is offered. Omitted, it goes last: one more than the highest position the portal already has.

integer

<= 999

Responses

201

The request type.

application/json

object

required

A UUID this API issued.

string format: uuid

portalId

required

A UUID this API issued.

string format: uuid

name

required

string

description

required

string | null

form

required

Array<object>

object

key

required

The key a submission sends this field’s value under.

string

>= 1 characters <= 60 characters /^[a-z0-9_]+$/

label

required

The heading this field becomes in the issue body.

string

>= 1 characters <= 120 characters

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

required

boolean

options

Array<string>

<= 50 items

helpText

string

<= 300 characters

destination

required

object

repositoryId

required

A UUID this API issued.

string format: uuid

repositoryFullName

required

string

labels

required

Array<string>

projectNodeId

required

string | null

initialFieldValues

required

object

key

additional properties

issueType

required

string | null

statusMap

required

Array<object>

First match wins, in the order given. An empty list means the default rules in ADR 0009.

object

when

required

One of:

object

kind

required

string

Allowed values: closed

stateReason

required

string | null

Allowed values: completed not_planned duplicate

status

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

position

required

integer

createdAt

required

string format: date-time

Example

{
  "form": [
    {
      "type": "text",
      "required": false
    }
  ],
  "statusMap": [
    {
      "when": {
        "kind": "closed",
        "stateReason": "completed"
      },
      "status": "Open"
    }
  ]
}

401

No valid credentials.

application/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

Example^generated

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

402

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

application/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

Example^generated

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

403

Authenticated, but not permitted.

application/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

Example^generated

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

404

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

application/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

Example^generated

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

409

The request conflicts with the current state.

application/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

Example^generated

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

422

The request did not match the expected shape.

application/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

Example^generated

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

429

Rate limited. Retry after the interval in the header.

application/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

Example^generated

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

502

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

application/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

Example^generated

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

Create a request type

Authorizations

Parameters

Path Parameters

Request Body

Responses

201

Example

401

Examplegenerated

402

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

422

Examplegenerated

429

Examplegenerated

502

Examplegenerated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated