API Reference — ClawPing Docs

Getting Started

ClawPing API Reference

The ClawPing REST API lets you programmatically create reminders, alerts, and recurring schedules — and receive notifications via Telegram or Email. The API follows REST conventions and returns JSON.

Base URL

All API requests are made to your ClawPing instance:

Base URL

https://api.clawping.xyz

Request Format

All requests must include Content-Type: application/json. All responses return JSON.

curl example

curl -X POST https://api.clawping.xyz/pings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "reminder", "message": "Hello!", "delay": "1m" }'

Security

Authentication

ClawPing uses Bearer token authentication. Include your token in every request's Authorization header.

POST /api/auth/token Generate API token ▼

Request Body

Field	Type	Description
secretrequired	string	Your API_SECRET_KEY from .env configuration
expires_in	string	Token TTL: `7d`, `30d`, `never` (default: never)

Request

curl -X POST https://api.clawping.xyz/auth/token \
  -H "Content-Type: application/json" \
  -d '{ "secret": "your-secret-key", "expires_in": "30d" }'

Response — 200

{
  "token": "cp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-27T00:00:00Z",
  "type": "Bearer"
}

200 OK 401 Invalid secret

Pings

Create a Ping

Schedule a time-based reminder delivered via Telegram or Email at the specified delay.

POST /pings Create a reminder ▼

Request Body

Field	Type	Description
typerequired	string	Must be `reminder`
messagerequired	string	The notification text (max 2000 chars)
delayrequired	string	Time until fire: `30s` `5m` `2h` `1d`
channelrequired	string	`telegram` or `email`
chat_id	string	Telegram chat ID (required if channel=telegram)
email	string	Email address (required if channel=email)

Request

curl -X POST https://api.clawping.xyz/pings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type":    "reminder",
    "message": "Deploy the new version to production",
    "delay":   "2h",
    "channel": "telegram",
    "chat_id": "437734870"
  }'

Response — 201

{
  "id":           "ping_7f3a9b2c",
  "status":       "scheduled",
  "type":         "reminder",
  "message":      "Deploy the new version to production",
  "channel":      "telegram",
  "chat_id":      "437734870",
  "scheduled_at": "2026-02-25T11:31:00Z",
  "created_at":   "2026-02-25T09:31:00Z",
  "metadata": {
    "delay_parsed": "2h",
    "delay_ms":     7200000
  }
}

201 Created 400 Invalid delay format 401 Unauthorized

GET /pings List all pings ▼

Query Parameters

Param	Type	Description
status	string	`scheduled` `fired` `cancelled` — filter by status
limit	integer	Max results to return (default: 20, max: 100)
offset	integer	Pagination offset (default: 0)

Request

curl https://api.clawping.xyz/pings?status=scheduled&limit=10 \
  -H "Authorization: Bearer $TOKEN"

Response — 200

{
  "total": 3,
  "limit": 10,
  "offset": 0,
  "pings": [
    { "id": "ping_7f3a9b2c", "status": "scheduled", "message": "Deploy...", "scheduled_at": "2026-02-25T11:31:00Z" },
    { "id": "ping_8a4b2d1e", "status": "scheduled", "message": "Standup", "scheduled_at": "2026-02-26T09:00:00Z" }
  ]
}

200 OK

GET /pings/{id} Get a specific ping ▼

Request

curl https://api.clawping.xyz/pings/ping_7f3a9b2c \
  -H "Authorization: Bearer $TOKEN"

200 OK 404 Not found

DEL /pings/{id}/cancel Cancel a scheduled ping ▼

Request

curl -X DELETE https://api.clawping.xyz/pings/ping_7f3a9b2c \
  -H "Authorization: Bearer $TOKEN"

Response — 200

{ "success": true, "id": "ping_7f3a9b2c", "status": "cancelled" }

200 Cancelled 404 Not found 400 Already fired

Condition Alerts

Monitor live conditions and fire notifications only when a threshold is crossed. Supports CoinGecko price data and custom webhooks.

POST /conditions Create a condition alert ▼

Field	Type	Description
typerequired	string	Must be `condition`
condition.assetrequired	string	CoinGecko asset ID: `bitcoin` `ethereum`
condition.operatorrequired	string	`above` or `below`
condition.thresholdrequired	number	Price threshold in USD
messagerequired	string	Notification text when condition fires
channelrequired	string	`telegram` or `email`
repeat	boolean	Re-arm after firing (default: false)

Request

curl -X POST https://api.clawping.xyz/conditions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "condition",
    "condition": {
      "asset":     "bitcoin",
      "operator":  "below",
      "threshold": 60000
    },
    "message": "BTC dropped below $60k — check positions",
    "channel": "telegram",
    "chat_id": "437734870",
    "repeat":  false
  }'

201 Created 400 Invalid condition

Webhooks

Agent Webhooks

Other agents in the Claw ecosystem can send notifications directly via the webhook endpoint. Authenticate with an agent key.

POST /webhook/agents Send an agent notification ▼

🔑

Agent Auth: Use X-Agent-Key: sk_agent_... header instead of Bearer token. Register your agent first via POST /webhook/agents/register.

Request

curl -X POST https://api.clawping.xyz/webhook/agents \
  -H "X-Agent-Key: sk_agent_clawscout_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":  "clawscout-v1.2",
    "priority":  "urgent",
    "recipient": {
      "channel": "telegram",
      "chat_id": "437734870"
    },
    "notification": {
      "title":     "🚨 Breaking: SEC approves Bitcoin ETF",
      "body":      "BTC price impact expected immediately.",
      "source_url":"https://reuters.com/article/..."
    }
  }'

Response — 200

{
  "success":   true,
  "ping_id":   "ping_webhook_9x2b",
  "delivered": true,
  "channel":   "telegram"
}

200 Delivered 401 Invalid agent key

POST /webhook/agents/register Register a new agent ▼

Request

curl -X POST https://api.clawping.xyz/webhook/agents/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":    "clawscout-v1.2",
    "name":        "ClawScout",
    "description": "News monitoring agent",
    "allowed_channels": ["telegram", "email"]
  }'

Response — 201

{
  "agent_key": "sk_agent_clawscout_abc123def456",
  "agent_id":  "clawscout-v1.2",
  "created_at":"2026-02-25T09:31:00Z"
}

201 Registered

Recurring

Recurring Schedules

Create cron-based recurring pings. Set once, repeat forever. Uses standard 5-field cron syntax.

POST /reminders Create a recurring schedule ▼

Field	Type	Description
cronrequired	string	5-field cron: `0 9 * * 1-5` = Mon–Fri 9am
messagerequired	string	Notification text
channelrequired	string	`telegram` or `email`
timezone	string	IANA timezone (default: server timezone)

Request

curl -X POST https://api.clawping.xyz/recurring \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cron":     "0 9 * * 1-5",
    "message":  "Daily standup — update your Jira tickets first!",
    "channel":  "telegram",
    "chat_id":  "437734870",
    "timezone": "Asia/Jakarta"
  }'

201 Scheduled 400 Invalid cron

Testing

Test Connections

Verify your channel configurations are working correctly.

POST /api/test/telegram Send Telegram test message ▼

Request

curl -X POST https://api.clawping.xyz/test/telegram \
  -H "Authorization: Bearer $TOKEN"

Response — 200

{ "success": true, "message": "Telegram connected ✓", "chat_id": "437734870" }

200 OK 400 Bot not configured

POST /api/test/email Send test email ▼

Request

curl -X POST https://api.clawping.xyz/test/email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "to": "you@example.com" }'

200 Sent 400 SMTP not configured

GET /health Service health check ▼

Request

curl https://api.clawping.xyz/health

Response — 200

{
  "status":    "ok",
  "version":   "1.0.0",
  "uptime":    "2d 4h 31m",
  "scheduler": "running",
  "db":        "connected",
  "telegram":  "connected",
  "email":     "connected"
}

200 OK

Reference

Errors & Codes

ClawPing uses standard HTTP status codes and returns structured error objects.

Error Format

{
  "error":   "INVALID_DELAY",
  "message": "Delay format '5x' is not valid. Use: 30s, 5m, 2h, 1d",
  "status":  400
}

Code	Status	Meaning
UNAUTHORIZED	401	Missing or invalid Bearer token
INVALID_DELAY	400	Delay format not recognized
INVALID_CHANNEL	400	Channel must be `telegram` or `email`
PING_NOT_FOUND	404	Ping ID does not exist
ALREADY_FIRED	400	Cannot cancel a ping that already fired
RATE_LIMIT	429	Too many pings created — limit per user exceeded
AGENT_KEY_INVALID	401	Agent key not registered or revoked
SMTP_FAILED	500	Email delivery failed — check SMTP config
TELEGRAM_FAILED	500	Telegram delivery failed — check bot token

⚡ Rate Limits Default limits per user ▼

Resource	Default Limit	Configurable
Max active pings	100 per user	MAX_PINGS_PER_USER in .env
API requests	300 / 15 min	RATE_LIMIT_WINDOW in .env
Webhook calls	60 / min per agent	WEBHOOK_RATE_LIMIT in .env