Core CRUD

Basic job creation, retrieval, update, deletion, and execution operations.

GET /api/jobs

Search and filter jobs with pagination.

Authentication: Required

Permissions: Returns jobs owned by or shared with the authenticated user

Query Parameters:

Parameter	Type	Default	Description
q	string	-	Full-text search query (searches name, description)
sort	string	name	Sort field (prefix with - for descending)
limit	integer	30	Results per page
start	integer	0	Pagination offset

Response:

The response is a paginated HAL collection. Job items are returned under _embedded["inf:job"].

{
  "_links": {
    "self": { "href": "/api/jobs{?sort,limit,start,q}", "templated": true }
  },
  "_embedded": {
    "inf:job": [
      {
        "_links": {
          "self": { "href": "/api/jobs/550e8400-..." }
        },
        "id": "550e8400-...",
        "type": "email",
        "name": "Daily Sales Report",
        "slug": "daily-sales-report",
        "description": "Send daily sales summary to management",
        "ownerId": "analytics",
        "interval": "0 8 * * *",
        "intervalType": "cron",
        "timezone": "America/New_York",
        "enabled": true,
        "nextRunAt": "2024-02-10T13:00:00.000Z",
        "startOn": "2024-01-01T00:00:00.000Z",
        "endOn": null,
        "lockedAt": null,
        "createdAt": "2024-01-15T09:00:00.000Z",
        "updatedAt": "2024-02-08T14:00:00.000Z"
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 15
}

---

GET /api/jobs-list

Get a lightweight flat list of readable jobs.

Authentication: Required

Response:

[
  {
    "id": "550e8400-...",
    "name": "Daily Sales Report",
    "type": "email",
    "enabled": true,
    "ownerId": "analytics",
    "ownerName": "Analytics Team",
    "naturalId": "analytics:daily-sales-report",
    "tags": ["tag-uuid-1"],
    "sharing": [
      { "principalId": "marketing", "accessLevel": 2 }
    ],
    "permissions": {
      "edit": true,
      "write": true,
      "delete": true,
      "share": true
    }
  }
]

---

GET /api/jobs/{id}

Get a single job with full details including datasets, actions, and driver info.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Job ID or {tenant}:{slug} natural ID

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "email",
  "name": "Daily Sales Report",
  "slug": "daily-sales-report",
  "description": "Send daily sales summary to management",
  "ownerId": "team:analytics",
  "interval": "0 8 * * *",
  "intervalType": "cron",
  "timezone": "America/New_York",
  "enabled": true,
  "nextRunAt": "2024-02-10T13:00:00Z",
  "lockedAt": null,
  "heartbeat": null,
  "startOn": "2024-01-01T00:00:00Z",
  "endOn": null,
  "data": {},
  "notes": "Configured by Alice on 2024-01-15",
  "source": null,
  "sourceId": null,
  "editingId": null,
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-02-08T14:00:00Z",
  "_links": {
    "self": { "href": "/api/jobs/550e8400-e29b-41d4-a716-446655440000" },
    "inf:job-history": { "href": "/api/jobs/550e8400-e29b-41d4-a716-446655440000/history" },
    "inf:job-actions": { "href": "/api/jobs/550e8400-e29b-41d4-a716-446655440000/actions" },
    "inf:job-datasets": { "href": "/api/jobs/550e8400-e29b-41d4-a716-446655440000/datasets" }
  },
  "permissions": {
    "read": true,
    "edit": true,
    "delete": true,
    "run": true
  }
}

---

POST /api/jobs

Create a new job.

Authentication: Required

Permissions: Requires permission.jobs.create

Request Body:

Field	Type	Required	Description
name	string	Yes	Job name
type	string	Yes	Job driver type
data	object	No	Driver-specific configuration
enabled	boolean	No	Enable immediately (default: false)
datasets	object	No	Dataset associations (keys are aliases, values are dataset IDs or {datasetId, snapshots})

Example:

{
  "name": "Daily Sales Report",
  "type": "email",
  "enabled": true,
  "datasets": {
    "sales": {
      "datasetId": "sales-2024",
      "snapshots": {
        "when": "before",
        "snapshotDatasets": ["sales-2024"]
      }
    }
  }
}

Response:

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Daily Sales Report",
  "type": "email",
  "ownerId": "alice",
  "timezone": "America/New_York",
  "enabled": true
}

---

PUT /api/jobs/{id}

Update an existing job's configuration.

Authentication: Required

Permissions: Requires job:edit permission

Path Parameters:

Parameter	Type	Description
id	string	Job ID or natural ID

Request Body:

Field	Type	Description
interval	string	Cron expression or simple interval
intervalType	string	cron, simple, or once
startOn	date	Start date
endOn	date	End date
enabled	boolean	Enable/disable job
data	object	Driver-specific data
name	string	Job name
description	string	Job description
notes	string	Admin notes
lockedAt	date	Lock status (admin only)
timezone	string	Timezone

Example:

{
  "interval": "0 9 * * *",
  "timezone": "America/Los_Angeles",
  "enabled": true
}

Response:

200 OK with updated job

---

DELETE /api/jobs/{id}

Delete a job.

Authentication: Required

Permissions: Requires job:delete permission (strict - owner only)

Path Parameters:

Parameter	Type	Description
id	string	Job ID or natural ID

Response:

204 No Content

---

POST /api/jobs/{id}

Run a job immediately (manual trigger).

Authentication: Required

Permissions: Requires job:run permission

Path Parameters:

Parameter	Type	Description
id	string	Job ID or natural ID

Response:

200 OK with job execution result

{
  "success": true,
  "duration": 1542,
  "history": [
    {
      "task": { "key": "job:progress.invoking_job" },
      "result": { "key": "job:status.success", "success": true }
    }
  ]
}

Long-Running

This endpoint may take minutes or hours depending on the job type. The socket timeout is disabled for job execution.

---

POST /api/jobs/{id}/_edit

Create a draft copy of a job for safe editing.

Authentication: Required

Permissions: Requires job:edit permission

Path Parameters:

Parameter	Type	Description
id	string	Job ID or natural ID

Response:

201 Created with draft job

{
  "id": "draft-job-abc-123",
  "name": "Daily Sales Report (Draft)",
  "editingId": "550e8400-e29b-41d4-a716-446655440000"
}

---

POST /api/jobs/{id}/_commit

Commit a draft job to replace the original.

Authentication: Required

Permissions: Requires job:edit permission

Path Parameters:

Parameter	Type	Description
id	string	Job ID or natural ID

Response:

200 OK with committed job

---

GET /api/jobs/{id}/owner

Get the current owner of a job.

Authentication: Required

Response:

{
  "ownerId": "team:analytics"
}

---

PUT /api/jobs/{id}/owner

Change the owner of a job.

Authentication: Required

Permissions: Requires job:edit permission

Request Body:

{
  "ownerId": "team:data-science"
}

Response:

200 OK

---

GET /api/jobs/{id}/favorite

Check if the current user has favorited a job.

Authentication: Required

Response:

{
  "favorited": true
}

---

PUT /api/jobs/{id}/favorite

Add a job to the current user's favorites.

Authentication: Required

Response:

200 OK

---

DELETE /api/jobs/{id}/favorite

Remove a job from favorites.

Authentication: Required

Response:

204 No Content