API Documentation

Schedule and manage background jobs with the Timelix Pulse API. All endpoints except health checks require authentication.

Authentication

Include the secret token in the Authorization header for all protected endpoints.

Authorization: Bearer YOUR_INITIATOR_SECRET

POST /schedule Schedule a one-time job

Request Body

Parameter	Type	Description
executeAt	string \| number required	When to execute (ISO datetime or unix timestamp ms)
payload	object required	JSON body that will be POSTed to the callback URL
callbackUrl	string	Callback URL (defaults to CALLBACK_URL env)
retries	number	Retry attempts on callback failure, 0–10 (default: 3)
jobId	string	Custom job ID (autogenerated if omitted)

Example Request

curl

curl -X POST https://pulse.timelix.ru/schedule \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "executeAt": "2026-07-12T10:00:00.000Z",
    "payload": { "toolId": "tool_123", "userId": "user_456" },
    "retries": 3
  }'

Response

json

{
  "success": true,
  "data": {
    "jobId": "job_abc123xyz",
    "executeAt": "2026-07-12T10:00:00.000Z"
  }
}

POST /schedules Create or replace a recurring schedule

Request Body

Parameter	Type	Description
pattern	string	Cron expression, e.g. "0 10-22 * * 1-5" (hourly 10:00–22:00 on weekdays). Exactly one of pattern / every
every	number	Interval in milliseconds, e.g. 3600000 = every hour. Exactly one of pattern / every
payload	object required	JSON body POSTed to the callback URL on every run
scheduleId	string	Stable schedule ID. POSTing again with the same ID replaces the schedule (upsert)
tz	string	IANA timezone for cron pattern, e.g. "Europe/Moscow"
startDate	string \| number	Do not fire before this date
endDate	string \| number	Do not fire after this date
limit	number	Stop after N runs
callbackUrl	string	Callback URL (defaults to CALLBACK_URL env)
retries	number	Retry attempts per run, 0–10 (default: 3)

Schedules firing more often than once per minute are rejected (configurable via SCHEDULE_MIN_INTERVAL_MS). Missed runs during downtime collapse into a single late run — no catch-up storm.

Example Request

curl

curl -X POST https://pulse.timelix.ru/schedules \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduleId": "daily-report-user_456",
    "pattern": "0 10-22 * * 1-5",
    "tz": "Europe/Moscow",
    "payload": { "toolId": "tool_123", "userId": "user_456" }
  }'

Response

json

{
  "success": true,
  "data": {
    "scheduleId": "daily-report-user_456",
    "pattern": "0 10-22 * * 1-5",
    "tz": "Europe/Moscow",
    "nextRunAt": "2026-07-13T07:00:00.000Z",
    "upcoming": ["2026-07-13T07:00:00.000Z", "2026-07-13T08:00:00.000Z", "..."]
  }
}

GET /schedules List recurring schedules

Query Parameters

Parameter	Type	Description
userId	string	Filter by payload.userId
companyId	string	Filter by payload.companyId
linkedAgentId	string	Filter by payload.linkedAgentId / payload.agentId
toolId	string	Filter by payload.toolId
limit	number	Max schedules to return (1–500)

Example Response

json

{
  "success": true,
  "data": [
    {
      "scheduleId": "daily-report-user_456",
      "pattern": "0 10-22 * * 1-5",
      "tz": "Europe/Moscow",
      "nextRunAt": "2026-07-13T07:00:00.000Z",
      "iterationCount": 12,
      "payload": { "toolId": "tool_123" }
    }
  ]
}

DELETE /schedules/:id Delete a recurring schedule

Example Request

curl

curl -X DELETE https://pulse.timelix.ru/schedules/daily-report-user_456 \
  -H "Authorization: Bearer YOUR_SECRET"

Response

json

{
  "success": true,
  "data": { "scheduleId": "daily-report-user_456" }
}

GET /jobs List all pending jobs

Query Parameters

Parameter	Type	Description
status	string	Filter by status: waiting, active, delayed
limit	number	Max number of jobs to return (default: 100)

Example Response

json

{
  "jobs": [
    {
      "id": "job_abc123",
      "name": "send-notification",
      "data": { "userId": 123 },
      "status": "delayed",
      "processAt": "2024-01-15T10:31:00.000Z"
    }
  ],
  "total": 1
}

DELETE /jobs/:id Cancel a scheduled job

Path Parameters

Parameter	Type	Description
id	string required	The job ID to cancel

Example Request

curl

curl -X DELETE https://pulse.timelix.ru/jobs/job_abc123 \
  -H "Authorization: Bearer YOUR_SECRET"

Response

json

{
  "success": true,
  "message": "Job cancelled"
}

GET /health Health check (no auth required)

Response

json

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "version": "0.1.0"
}

Callback Contract

On every run Pulse POSTs the job payload (as-is, JSON) to the callback URL. Non-2xx responses are retried with exponential backoff; request timeout is 30s. Use the headers below for deduplication — delivery is at-least-once.

Header	Description
X-Initiator-Job-Id	Unique ID of this run (unique per occurrence for recurring schedules)
X-Initiator-Schedule-Id	Stable schedule ID (present only for recurring schedules)
X-Initiator-Scheduled-For	ISO datetime the run was scheduled for (may differ from delivery time)
X-Initiator-Attempt	Delivery attempt number (1-based, increments on retries)