Replace a Source's API key

POST

/v1/sources/{id}/key

const url = 'https://api.pocketbell.dev/v1/sources/src_01jz9k6q8r3tfv0x2m4n5p7s8a/key';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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.pocketbell.dev/v1/sources/src_01jz9k6q8r3tfv0x2m4n5p7s8a/key \
  --header 'Authorization: Bearer <token>'

The old key stops working at once. The new one is shown only this once.

Authorizations

session

Parameters

Path Parameters

required

string

Example

src_01jz9k6q8r3tfv0x2m4n5p7s8a

Responses

200

The new key.

application/json

object

source

required

object

required

string

name

required

string

kind

required

Api: sends with an API key. webhook: another service posts events to its URL.

string

Allowed values: api webhook

title_template

required

Webhook only: the title, with {{field}} placeholders.

string | null

message_template

required

Webhook only: the message; empty means a summary of the event.

string | null

last_event_at

required

Webhook only: when the latest event arrived.

string | null format: date-time

priority_field

required

Webhook only: the field whose value sets the priority; null: always the default.

string | null

priority_values

Webhook only: the priority for each value of priority_field, the first match winning. Any other value gets the default.

Array<object>

object

value

required

string

>= 1 characters <= 100 characters

priority

required

string

Allowed values: silent quiet normal important critical

replace_field

required

Webhook only: the field whose value is the replace key, so a later event with the same value replaces the earlier notification; null: none.

string | null

device_ids

required

The devices it sends to, of those still receiving; null: every device, including new ones. If every chosen device is removed, it sends to every device.

Array<string> | null

api_key_hint

required

Identifies the key without revealing it.

string

default_priority

required

string

Allowed values: silent quiet normal important critical

sound

required

The sound its notifications play; null: the device’s own.

string | null

Allowed values: default bell chime ping pulse rise alarm none

critical_sound

required

Always null: every Critical notification plays the Critical sound.

string | null

Allowed values: default bell chime ping pulse rise alarm none

messages_24h

required

Notifications sent in the last 24 hours.

integer

automatic_tool

Webhook only: the tool its latest event is from, when Pocketbell writes its notifications (no template of its own); null otherwise.

string | null

last_message_at

When it last sent a notification that was taken, within the plan’s history.

string | null format: date-time

last_refused

The last notification it sent that was refused, and why: the sender alone saw the error.

object

code

required

The error the sender got: monthly_limit_reached, rate_limited, pro_required or question_limit.

string

required

string format: date-time

created_at

required

string format: date-time

api_key

required

API Sources. Shown once: only its hash is kept.

string | null

webhook_token

required

Webhook Sources. Shown once. The URL is /v1/hooks/{webhook_token} on this server.

string | null

Example

{
  "source": {
    "id": "src_01jz9k6q8r3tfv0x2m4n5p7s8a",
    "name": "Production Servers",
    "kind": "api",
    "priority_field": "status",
    "priority_values": [
      {
        "value": "down",
        "priority": "silent"
      }
    ],
    "replace_field": "check",
    "api_key_hint": "pb_live_8fK2…Qx4a",
    "default_priority": "silent",
    "sound": "default",
    "critical_sound": "default",
    "automatic_tool": "Uptime Kuma",
    "last_refused": {
      "code": "monthly_limit_reached"
    }
  },
  "api_key": "pb_live_…",
  "webhook_token": "pbw_…"
}

401

Missing or ended session.

application/json

object

error

required

object

code

required

string

message

required

string

details

Which fields were wrong, for invalid_request.

Array<object>

object

field

required

string

message

required

string

Example

{
  "error": {
    "code": "invalid_request"
  }
}

404

No such Source on this account.

application/json

object

error

required

object

code

required

string

message

required

string

details

Which fields were wrong, for invalid_request.

Array<object>

object

field

required

string

message

required

string

Example

{
  "error": {
    "code": "invalid_request"
  }
}