Quickstart

This guide walks you through signing up, creating a job, and inspecting its execution. You can follow along with curl, the CLI, or any HTTP client.

1. Create an account

curl -X POST https://api.trigrun.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "[email protected]",
    "password": "your-secure-password",
    "workspace_name": "My Workspace"
  }'

The response includes a JWT token and your workspace details:

{
  "token": "eyJhbGciOi...",
  "workspace": {
    "id": "clx...",
    "name": "My Workspace",
    "slug": "my-workspace-a1b2c3",
    "timezone": "UTC"
  },
  "user": {
    "id": "clx...",
    "name": "Alice",
    "email": "[email protected]"
  }
}

Save the token value — you'll use it for all subsequent requests.

export TOKEN="eyJhbGciOi..."

2. Create a job

Create a recurring job that hits a URL every 5 minutes:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "health-check",
    "kind": "recurring",
    "schedule": {
      "every_n_minutes": 5,
      "timezone": "UTC"
    },
    "request": {
      "url": "https://httpbin.org/post",
      "method": "POST",
      "headers": {
        "X-Source": "trigrun"
      },
      "timeout_seconds": 30
    },
    "retry_policy": {
      "max_attempts": 3,
      "retry_on_statuses": [429, 500, 502, 503, 504]
    }
  }'

The response includes the job ID and its next scheduled run:

{
  "id": "clx...",
  "name": "health-check",
  "state": "active",
  "kind": "recurring",
  "next_run_at": "2026-03-15T10:05:00.000Z",
  "request": {
    "url": "https://httpbin.org/post",
    "method": "POST"
  }
}

3. Trigger it now

Don't want to wait for the next scheduled run? Trigger it immediately:

curl -X POST https://api.trigrun.com/v1/jobs/JOB_ID/run-now \
  -H "Authorization: Bearer $TOKEN"

4. Check the execution

List executions for your job:

curl https://api.trigrun.com/v1/jobs/JOB_ID/executions \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    {
      "id": "clx...",
      "job_name": "health-check",
      "status": "succeeded",
      "scheduled_for": "2026-03-15T10:00:00.000Z",
      "attempts": [
        {
          "number": 1,
          "status": "SUCCESS",
          "statusCode": 200,
          "latencyMs": 142
        }
      ]
    }
  ],
  "total": 1
}

5. Try other schedule types

Cron expression — run at 2 AM New York time every day:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-cleanup",
    "kind": "cron",
    "schedule": {
      "cron": "0 2 * * *",
      "timezone": "America/New_York"
    },
    "request": {
      "url": "https://api.example.com/cleanup",
      "method": "POST"
    }
  }'

One-time immediate — fire once right now:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "one-shot",
    "kind": "one_time",
    "request": {
      "url": "https://api.example.com/trigger",
      "method": "POST"
    }
  }'

Using the CLI instead

If you prefer the terminal:

# Install
npm install -g @cron/cli

# Authenticate
cronctl login -e [email protected] -p your-secure-password

# Create a recurring job
cronctl jobs create \
  --name health-check \
  --url https://httpbin.org/post \
  --method POST \
  --kind recurring \
  --every 5

# List jobs
cronctl jobs list

# Trigger immediately
cronctl jobs run JOB_ID

# Check executions
cronctl executions list --job JOB_ID

Next steps

Authentication — JWT tokens, API tokens, and how auth works
Jobs guide — All schedule types, retry policies, and job configuration
Notifications — Set up alerts for job success or failure
Secrets — Store and reference encrypted credentials