Library Import Jobs

Get All Library Import Jobs

This endpoint retrieves a list of Library Import Job resources. This endpoint and all of the following are only available when the "Import/Export Version 2 (beta)" feature flag is on.

GET /api/v2/library/import/

Query parameters

The following parameters may be used to filter the Library Import Job resources in the response.

Parameter Description
ordering Sort Library Import Jobs by the specified field. Prefix field name with minus to sort descending. Sortable fields: id, status, triggered_by, triggered.
status Given a status, will filter Library Import Jobs by their status. Valid statuses: pending, generating_diff, ready_for_review, applying_changes, success, fail, cancel.
status__in Given a list of statuses separated by ,s, returns all Library Import Jobs matching specified statuses. 
GET /api/v2/library/import/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "id": 1,
            "status": "success",
            "triggered": "2025-06-06T16:20:24.332063-04:00",
            "triggered_by": {
                "id": 1,
                "email": "admin@example.com",
                "first_name": "Admin",
                "last_name": "Testerton"
            },
            "accepted": "2025-06-06T17:20:24.332063-04:00",
            "accepted_by": {
                "id": 1,
                "email": "admin@example.com",
                "first_name": "Admin",
                "last_name": "Testerton"
            },
            "completed": "2025-06-06T18:20:24.332063-04:00",
            "errors": null
        }
    ]
}

Get a specific Library Import Job

This endpoint retrieves a single Library Import Job resource, as specified by the id parameter.

GET /api/v2/library/import/{job_id}/

URL Parameters

Parameter Description
job_id The id of the Library Import Job to retrieve 
GET /api/v2/library/import/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "status": "success",
    "triggered": "2025-06-06T16:20:24.332063-04:00",
    "triggered_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "accepted": "2025-06-06T17:20:24.332063-04:00",
    "accepted_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "completed": "2025-06-06T18:20:24.332063-04:00",
    "errors": null
}

Get the currently in progress Library Import Job

This endpoint retrieves the currently in progress Library Import Job resource or responds with a 404 error if there is no in progress job.

GET /api/v2/library/import/current/

GET /api/v2/library/import/current/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "status": "generating_diff",
    "triggered": "2025-06-06T16:20:24.332063-04:00",
    "triggered_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "accepted": null,
    "accepted_by": null,
    "completed": null,
    "errors": null
}

Create a Library Import Job

This endpoint creates a new Library Import Job resource and starts the job automatically.

POST /api/v2/library/import/

Fields Required Description
files Yes The file(s) to be imported into Library. Only one file per content model can be uploaded. Supported file formats are CSV, JSON, Excel and YAML. All files uploaded to a single job must have the same format. The available content models are: standard. 
POST /api/v2/library/import/ HTTP/1.1
Content-Type: multipart/form-data
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"


Content-Disposition: form-data; name="files"; filename="standard.csv"
Content-Type: text/csv
<truncated>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "status": "pending",
    "triggered": "2025-06-06T16:20:24.332063-04:00",
    "triggered_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "accepted": null,
    "accepted_by": null,
    "completed": null,
    "errors": null
}

Update a Library Import Job

This endpoint updates a specific Library Import Job resource, as specified by the id parameter, allowing for changes to be accepted or for the job to be cancelled or retried.

PATCH /api/v2/library/import/{job_id}/

URL Parameters

Parameter Description
job_id The id of the Library Import Job to update.

Payload

Fields Required Description
status Yes The status the Library Import Job should be updated to. Valid options: cancel, accept_changes and retry.
wait_for_task No Whether to wait for confirmation that the running task has been cancelled (default: true, recommended for synchronous operations).

Notes on cancelling jobs:

  • Only jobs which are pending, generating_diff, ready_for_review or applying_changes may be cancelled.
  • When cancelling a pending job, the status will change immediately to indicate it has been cancelled.
  • When cancelling an in progress job, the status of the job will be updated only once the job has successfully terminated in the system. The status in the response will still indicate the job as in progress, so you will need to request the job's details until the job terminates to see the status update.

Notes on accepting changes:

  • Only jobs which are ready_for_review allow for changes to be accepted.

Notes on retrying jobs:

  • Only jobs which have a status of fail or cancel may be retried.
  • The triggered time and user will be changed to the user who triggers the retry operation. Any errors from the previous run will be cleared out.
PATCH /api/v2/library/import/1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "status": "cancel"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "status": "cancel",
    "triggered": "2025-06-17T15:16:01.793773-04:00",
    "triggered_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "accepted": null,
    "accepted_by": null,
    "completed": "2025-06-17T15:16:01.885591-04:00",
    "errors": null
}

Get Library Import Job Diff Summary

This endpoint retrieves a list of summary count data for Library Import Job Diff resources, which details the number of added, updated and deleted objects for each content model in a Library Import Job.

GET /api/v2/library/import/{job_id}/diff/

URL Parameters

Parameter Description
job_id The id of the Library Import Job the Library Import Job Diff summary data to list belongs to. 
GET /api/v2/library/import/1/diff/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "content_model": "standard",
            "add": 1,
            "update": 2,
            "delete": 0
        }
    ]
}

Get a specific Library Import Job Diff

This endpoint retrieves a single Library Import Job Diff resource, which details the old and new states of the objects that will be added, updated and deleted by the Library Import Job for a given content model.

GET /api/v2/library/import/{job_id}/diff/{content_model}/

URL Parameters

Parameter Description
job_id The id of the Library Import Job the Library Import Job Diff summary data to retrieve belongs to.
content_model The content model of the Library Import Job Diff to retrieve. Valid content types: standard. 
GET /api/v2/library/import/1/diff/standard/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "content_model": "standard",
    "add": [
        {
            "original": {},
            "new": {
                "id": "CT2",
                "title": "New Standard",
                "text": "New Standard Text",
                "problem": "P12",
                "priority": 8,
                "phase": "X1",
                "active": false,
                "match_conditions": "A1 AND !A2;A3",
                "tags": ""
            },
            "entry": 1
        }
    ],
    "update": [
        {
            "original": {
                "id": "T1",
                "title": "Original Standard",
                "text": "Original Text",
                "problem": "P21",
                "priority": 5,
                "phase": "X5",
                "active": true,
                "mark_delete": false,
                "match_conditions": "",
                "tags": ""
            },
            "new": {
                "id": "T1",
                "title": "Updated Standard",
                "text": "Updated Standard Text",
                "problem": "P12",
                "priority": 8,
                "phase": "X1",
                "active": false,
                "mark_delete": false,
                "match_conditions": "A4;A5 AND !A6",
                "tags": ""
            },
            "entry": 2
        }
    ],
    "delete": [
        {
            "original": {
                "id": "CT1",
                "title": "Standard to delete",
                "text": "Standard Text to delete",
                "problem": "P12",
                "priority": 5,
                "phase": "X5",
                "active": true,
                "mark_delete": false,
                "match_conditions": "A7",
                "tags": ""
            },
            "new": {},
            "entry": 3
        }
    ]
}

results matching ""

    No results matching ""