Skip to content
PocketbellAPI

Create a Source

POST
/v1/sources
curl --request POST \
  --url https://api.pocketbell.dev/v1/sources \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Production Servers", "kind": "api", "default_priority": "silent" }'

Returns the new Source’s API key. It is shown only this once.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 60 characters
Example
Production Servers
kind

Defaults to api.

string
Allowed values: api webhook
default_priority

Defaults to normal.

string
Allowed values: silent quiet normal important critical

Responses

Section titled “Responses”

201

Section titled “201”

Created.

Media typeapplication/json
object
source
required
object
id
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
at
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_…"
}

400

Section titled “400”

The request was invalid.

Media typeapplication/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"
  }
}

401

Section titled “401”

Missing or ended session.

Media typeapplication/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"
  }
}

403

Section titled “403”

The plan’s Source limit is reached.

Media typeapplication/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"
  }
}