Conversion jobs

Retrieve, list, cancel, or delete the short-lived jobs created by your conversion requests. All routes require a bearer token and use POST with a JSON body.

A user principal can access only its own jobs. A privileged principal can use the owner filter and access jobs across owners when its role permits it.

Routes

Route	Required fields	Optional fields	Success result
/v1/job/get	job_id	—	Job metadata and source.
/v1/job/list	—	status, input_format, output_format, owner, paging fields	A page of job metadata.
/v1/job/result	job_id	—	Completed job output.
/v1/job/cancel	job_id	—	Cancellation state.
/v1/job/delete	job_id	—	Deletion confirmation.

Request fields

Field	Routes	Type	Description
job_id	get, result, cancel, delete	String	Required dashed UUID. id is accepted as a legacy alias; use job_id in new integrations.
status	list	String	One of pending, running, completed, failed, cancelled, or expired.
input_format	list	String	Input format name or dashed UUID.
output_format	list	String	Output format name or dashed UUID.
owner	list	String	Owner UUID for a privileged principal. A user principal always receives only its own jobs.
limit	list	Integer	Page size from 1 through 100; default 3. Values below 1 reset to 3, and values above 100 are capped at 100.
cursor	list	String	Opaque cursor returned by next_cursor.
offset	list	Integer	Zero-based row offset.
page_number	list	Integer	One-based page number.

cursor takes precedence over offset, which takes precedence over page_number. Invalid values fail with invalid cursor, invalid offset, or invalid page_number.

Job states

Use status to decide the next action:

State	Next action
pending or running	Poll /v1/job/result later, or cancel when appropriate.
completed	Retrieve the output with /v1/job/result.
failed	Inspect /v1/job/get for error metadata; /v1/job/result returns job failed.
cancelled or expired	Do not expect a result; submit a new conversion if needed.

List jobs

The data object contains items, limit, total_count, next_offset, page_number, page_total, and next_cursor. Each item contains job_id, owner, operation, mode, status, input_format, output_format, profile, timestamps, expires_at, and metadata.

curl -sS https://api.document.m7.org/v1/job/list \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "completed",
    "limit": 10
  }'

Use the returned next_cursor verbatim for the next page. It is null when there is no next page.

{
  "status": 1,
  "comment": "JOB_LIST",
  "data": {
    "items": [
      {
        "job_id": "JOB_UUID",
        "owner": "OWNER_UUID",
        "operation": "convert",
        "mode": "async",
        "status": "completed",
        "input_format": "markdown",
        "output_format": "html",
        "profile": null,
        "created_at": "2030-01-01 11:59:59",
        "started_at": "2030-01-01 11:59:59",
        "completed_at": "2030-01-01 12:00:00",
        "cancelled_at": null,
        "expires_at": "2030-01-01 13:00:00",
        "metadata": null
      }
    ],
    "limit": 10,
    "total_count": 1,
    "next_offset": 10,
    "page_number": 1,
    "page_total": 1,
    "next_cursor": null
  }
}

Retrieve a completed result

/v1/job/result returns the job metadata, original source, source hash and size, plus result, result_format, result_bytes, warnings, issues, duration_ms, and result metadata. It fails with job not completed until the job is complete, job failed for a failed job, and job expired after the retention period.

curl -sS https://api.document.m7.org/v1/job/result \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_id": "JOB_UUID"
  }'

Cancel or delete a job

/v1/job/cancel returns job_id, status: "cancelled", and cancelled_at. It cannot cancel a completed, failed, or already cancelled job.

/v1/job/delete permanently removes the job and its retained input and result data, returning job_id and deleted: true. Use it only after the data is no longer needed.