Semestra

Background jobs

Cancel a pending or running background job.

POST
/jobs/{job_id}/cancel

Use when the user wants to stop a background operation. A running job stops at its next checkpoint, so it may still finish. Cancelling a finished job changes nothing.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

job_id*Job Id

Job id, as returned when the job was started.

Response Body

Successful Response

application/json
  1. response
id*Id
kind*Kind
status*Status
Value in"pending""running""succeeded""failed""cancelled"
progress*Progress
step*string|null
step_current*integer|null
step_total*integer|null
result*|null
error_code*string|null
error_params*|null
attempts*Attempts
max_attempts*Max Attempts
cancel_requested*Cancel Requested
created_at*Created At
Formatdate-time
started_at*|null
finished_at*|null
waiting?|null
Example Request
curl -X POST 'https://example.com/jobs/string/cancel'
Example Response
{  "id": "string",  "kind": "string",  "status": "pending",  "progress": 0,  "step": "string",  "step_current": 0,  "step_total": 0,  "result": {},  "error_code": "string",  "error_params": {},  "attempts": 0,  "max_attempts": 0,  "cancel_requested": true,  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "waiting": {    "reason": "string",    "until": "2019-08-24T14:15:22Z"  }}

Get the state and progress of a background job.

GET
/jobs/{job_id}

Use to check on a long-running operation (file parsing, imports, syncs) that another capability started and returned a job id for.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Path Parameters

job_id*Job Id

Job id, as returned when the job was started.

Response Body

Successful Response

application/json
  1. response
id*Id
kind*Kind
status*Status
Value in"pending""running""succeeded""failed""cancelled"
progress*Progress
step*string|null
step_current*integer|null
step_total*integer|null
result*|null
error_code*string|null
error_params*|null
attempts*Attempts
max_attempts*Max Attempts
cancel_requested*Cancel Requested
created_at*Created At
Formatdate-time
started_at*|null
finished_at*|null
waiting?|null
Example Request
curl -X GET 'https://example.com/jobs/string'
Example Response
{  "id": "string",  "kind": "string",  "status": "pending",  "progress": 0,  "step": "string",  "step_current": 0,  "step_total": 0,  "result": {},  "error_code": "string",  "error_params": {},  "attempts": 0,  "max_attempts": 0,  "cancel_requested": true,  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z",  "waiting": {    "reason": "string",    "until": "2019-08-24T14:15:22Z"  }}

List the user's background jobs, newest first.

GET
/jobs

Use to find recent or running background operations and their outcome. Do not use to read the data a job produced; use the capability of the module that owns it.

Authorization

cookiesemestra_session<token>

Set by the sign-in endpoints for the web app. Requests other than GET, HEAD and OPTIONS also need the X-Semestra-CSRF header set to the semestra_csrf cookie.

Query Parameters

status?|

Only jobs in this state.

kind?|

Only jobs of this kind, e.g. files.parse.

cursor?|

next_cursor of the previous page.

limit?Limit

Page size.

Default20

Response Body

Successful Response

application/json
  1. response
items*array<>
next_cursor*string|null
Example Request
curl -X GET 'https://example.com/jobs'
Example Response
{  "items": [    {      "id": "string",      "kind": "string",      "status": "pending",      "progress": 0,      "step": "string",      "step_current": 0,      "step_total": 0,      "result": {},      "error_code": "string",      "error_params": {},      "attempts": 0,      "max_attempts": 0,      "cancel_requested": true,      "created_at": "2019-08-24T14:15:22Z",      "started_at": "2019-08-24T14:15:22Z",      "finished_at": "2019-08-24T14:15:22Z",      "waiting": {        "reason": "string",        "until": "2019-08-24T14:15:22Z"      }    }  ],  "next_cursor": "string"}