API Documentation

POST/GET /checkin/<token>

Send a check-in signal for your canary.

URL Parameters:

Parameter	Type	Description
token	string	Your canary's unique token (found in dashboard)

Request Parameters:

Parameter	Type	Required	Description
message	string	No	Custom message to log with the check-in (max 500 characters)

Request Methods:

• GET: Message can be passed as query parameter
• POST: Message can be passed as form data or JSON

Response Format:

{
  "status": "success",
  "message": "Check-in received",
  "received_message": "Your custom message here"  // Only if message was provided
}

Error Response:

{
  "status": "error",
  "message": "Invalid token"
}

1. Simple GET Request

GET /checkin/abc123def456
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Check-in received"
}

2. GET with Message

GET /checkin/abc123def456?message=Task%20completed%20successfully
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Check-in received",
  "received_message": "Task completed successfully"
}

3. POST with Form Data

POST /checkin/abc123def456
Content-Type: application/x-www-form-urlencoded

message=Processed+1234+records+in+5.2+seconds

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Check-in received",
  "received_message": "Processed 1234 records in 5.2 seconds"
}

4. POST with JSON

POST /checkin/abc123def456
Content-Type: application/json

{
  "message": "Database backup completed - 2.3GB backed up"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Check-in received",
  "received_message": "Database backup completed - 2.3GB backed up"
}

Status Code	Description
200 OK	Check-in successful
404 Not Found	Invalid token or canary not found
400 Bad Request	Malformed request (rarely encountered)
500 Internal Server Error	Server error - please try again

Currently there are no strict rate limits, but excessive requests may be throttled. Best practices:

• Don't check in more frequently than your configured interval
• Use reasonable timeouts in your client code
• Implement exponential backoff for retries

cURL

curl -X POST "https://silentcanary.com/checkin/YOUR_TOKEN" \
     -d "message=Script completed successfully"

Python (requests)

import requests

response = requests.post(
    'https://silentcanary.com/checkin/YOUR_TOKEN',
    json={'message': 'Python script completed'}
)
print(response.json())

Node.js (fetch)

const response = await fetch('https://silentcanary.com/checkin/YOUR_TOKEN', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        message: 'Node.js task completed'
    })
});
const result = await response.json();
console.log(result);

PowerShell

$body = @{
    message = "PowerShell script completed"
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://silentcanary.com/checkin/YOUR_TOKEN" `
                  -Method POST `
                  -Body $body `
                  -ContentType "application/json"

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func checkin() {
    data := map[string]string{
        "message": "Go service check-in",
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "https://silentcanary.com/checkin/YOUR_TOKEN",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        // handle error
    }
    defer resp.Body.Close()
}