REST API

API Reference

Complete documentation for the Talarius REST API.

Base URL

https://v1.talarius.io

Authentication

All API requests require authentication via your project's API key. Include it in one of these headers:

X-API-Key header (recommended)
X-API-Key: tk_live_your_api_key
Authorization header
Authorization: Bearer tk_live_your_api_key

API key prefixes

  • tk_live_ - Production keys
  • tk_test_ - Test keys (sandbox)

Rate Limits

Limit Value Scope
Inbound requests 100/min Account-wide
Outbound delivery 1/min Per project
Message buffer 100 messages Per project

When rate limited, you'll receive a 429 response with a Retry-After header.

POST

/alerts

Send an alert to your configured destination.

Request Body

Parameter Type Required Description
title string Yes Alert title (max 256 chars)
body string No Alert body (max 4096 chars)
priority string No "normal" or "high" (default: normal)

Optional Headers

Header Description
Idempotency-Key Prevents duplicate alerts. TTL: 24 hours. Learn more

Example Request

curl 
curl -X POST https://v1.talarius.io/alerts \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"title": "Server Alert", "body": "CPU at 95%", "priority": "high"}'

Response

202 Accepted
{
  "accepted": true,
  "alertId": "alert_a1b2c3d4e5f6...",
  "queued": true
}
200 Duplicate (idempotent)
{
  "accepted": true,
  "alertId": "alert_original...",
  "duplicate": true
}
POST

/heartbeats

Send a heartbeat ping to monitor your service's uptime.

Request Body

Parameter Type Required Description
interval number No Expected interval in minutes (1-60, default: 5)

Example Request

curl 
curl -X POST https://v1.talarius.io/heartbeats \
  -H "X-API-Key: tk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"interval": 5}'

Response

200 OK
{
  "state": "healthy",
  "transition": null
}

The transition field will contain details when the heartbeat state changes (e.g., from failing to healthy).

Error Codes

All errors follow a consistent format with a machine-readable code.

Error response format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title is required",
    "details": { ... }
  }
}
Code HTTP Description
UNAUTHORIZED 401 API key is missing from request
INVALID_API_KEY 401 API key not found or invalid format
API_KEY_EXPIRED 401 API key has been revoked
PROJECT_DISABLED 401 Project is disabled
ACCOUNT_SUSPENDED 401 Account has been suspended
VALIDATION_ERROR 400 Invalid request payload
INVALID_CONTENT_TYPE 400 Request body must be valid JSON
RATE_LIMIT_EXCEEDED 429 Too many requests, retry later
BUFFER_OVERFLOW 503 Message buffer is full
INSUFFICIENT_CREDITS 402 No credits available

Related

Idempotency

Prevent duplicate alerts

Examples

Real-world use cases