API Reference

SilentFail API Documentation

Complete reference for integrating job monitoring into your applications. Simple HTTP endpoints, no SDKs required.

Quick Start

Get started with SilentFail in 3 simple steps:

Create a job in your SilentFail dashboard
Copy the job token from the job details page
Add ping calls to your background job code

Base URL

https://silentfail.dev/api/ping/

Authentication

Authentication is done via job tokens in the URL path. No API keys or headers required. Each job has a unique token that you can find in your dashboard.

https://silentfail.dev/api/ping/YOUR_JOB_TOKEN/start

API Endpoints

POSTJob Start

Optional

Signal that your job has started execution. This helps track job duration and detect stuck jobs.

Endpoint

POST /api/ping/{token}/start

Query Parameters

Parameter	Type	Description
msg	string	Optional message describing the job run

curl -X POST "https://silentfail.dev/api/ping/YOUR_JOB_TOKEN/start?msg=Processing%20batch%201"

POSTJob Success

Required

Signal that your job completed successfully. This resets any failure alerts and updates the job status to OK.

Endpoint

POST /api/ping/{token}/success

Query Parameters

Parameter	Type	Description
msg	string	Optional success message
duration	integer	Job duration in milliseconds

curl -X POST "https://silentfail.dev/api/ping/YOUR_JOB_TOKEN/success?duration=5420&msg=Processed%20100%20records"

POSTJob Failure

Recommended

Signal that your job failed. This immediately triggers failure alerts and updates the job status to Failed.

Endpoint

POST /api/ping/{token}/fail

Query Parameters

Parameter	Type	Description
msg	string	Error message or failure reason

curl -X POST "https://silentfail.dev/api/ping/YOUR_JOB_TOKEN/fail?msg=Database%20connection%20failed"

Response Format

All endpoints return JSON responses with the same format:

Success Response (200 OK)

{
  "ok": true,
  "job": "daily-backup",
  "action": "success",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Response (4xx/5xx)

{
  "error": "Job not found"
}

Best Practices

1. Use Short Timeouts

Set HTTP timeouts to 3-5 seconds to prevent your jobs from blocking on network issues. SilentFail pings should not slow down your critical processes.

2. Handle Network Failures Gracefully

Don't let ping failures crash your jobs. Wrap ping calls in try-catch blocks and continue with your job logic if the ping fails.

3. Set Realistic Expected Intervals

Configure expected intervals with some buffer time to avoid false positive alerts. If your job runs every hour, set the expected interval to 70-80 minutes.

4. Use Meaningful Messages

Include helpful context in your ping messages, like record counts, batch IDs, or error details. This makes debugging much easier.

Complete Example

Here's a complete example of instrumenting a background job:

// daily-backup.js
const SILENT_FAIL_TOKEN = process.env.SILENT_FAIL_TOKEN;

async function ping(action, params = {}) {
  const url = new URL(`https://silentfail.dev/api/ping/${SILENT_FAIL_TOKEN}/${action}`);
  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.append(key, value);
  });

  try {
    await fetch(url.toString(), {
      method: 'POST',
      timeout: 5000 // 5 second timeout
    });
  } catch (error) {
    console.warn('Ping failed:', error.message);
    // Don't throw - continue with job
  }
}

async function runBackup() {
  const startTime = Date.now();

  try {
    await ping('start', { msg: 'Starting daily backup' });

    // Your backup logic here
    const backupResult = await performBackup();

    const duration = Date.now() - startTime;
    await ping('success', {
      msg: `Backup completed. ${backupResult.files} files backed up`,
      duration
    });

  } catch (error) {
    await ping('fail', {
      msg: error.message
    });
    throw error;
  }
}

runBackup().catch(console.error);

Need help? Check out our full documentation or contact support.