API Documentation | xTract2AI

🔑 API Key Management

API Key Generation:

API keys can only be generated by managers through the admin panel.
Each API key has an assigned owner.
Each user has an assigned Role.

👥 User Roles & Access Control

User Roles:

Manager: Can access data at organization level (all files and extractions across the organization)
Member: Can only access their owned contents (files uploaded by them and associated extractions)

🔗 Webhook Management

Webhook Creation: Webhooks can only be created by managers through the admin panel. Each webhook has an assigned owner.

Configuration: Managers need to describe the endpoint URL and select the event type for the webhook.

Supported Events:

content_extraction_completed: Triggers when content extraction is completed (both success and failure cases)

The system will automatically send event details to the configured webhook endpoint when the specified event occurs.

📤 Sample Webhook Body

Event: content_extraction_completed

Webhook Payload:

{
  "content_extraction_id": 91,
  "scorm_file_id": 31,
  "batch_name": "",
  "download_url":"some_downloadable_url_link"
  "status": "completed",
  "finished_at": "2025-07-10T07:36:54.620631+00:00",
  "started_at": "2025-07-10T13:06:53.557708+00:00",
}

Payload Fields:

content_extraction_id: Unique identifier of the extraction process
scorm_file_id: ID of the associated SCORM file
status: Current status of the extraction (completed/failed)
started_at: When the extraction process started
finished_at: When the extraction completed (null if still in progress)

POST /scorm-files/upload/

Tag: Scorm

Upload a SCORM file or register a public URL

*Once uploaded, system will automatically start the content extraction process.*

Request Example:

{
    "public_url": "https://cdn.example.com/files/your-file.zip",
    "batch_name": "example_batch_name"
}

Alternative Request Example (multipart/form-data):

Form fields:
  file: <the SCORM file itself>
  batch_name: example_batch_name

Example using cURL:

curl -X POST https://your-api.com/scorm-files/upload/ \
  -F "file=@/path/to/your-file.zip" \
  -F "batch_name=example_batch_name"

Response Example status 200

{
    "scorm_file_id": 38,
    "file_name": "file_name_in_text",
    "scorm_file": {
        "id": 38,
        "file_name": "file_name_in_text",
        "user": 1,
        "status": "processing",
        "storage_path": "storage_path_in_s3",
        "batch_name": "Lorem ipsuaasdasdasdasdasdasdasdasdasdaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "file_size": null,
        "created_at": "2025-07-18T13:30:33.587545Z",
        "updated_at": "2025-07-18T13:30:33.604954Z",
        "content_extractions": [],
        "last_extraction": null,
        "public_url": "public_url_if_given",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remark": "File uploaded and validation started."
    },
    "message": "File is being processed and content extraction will start automatically."
}

Important Parameters:

scorm_file_id: Unique identifier for the uploaded SCORM package. This shall be used later to fetch extraction details and download the extracted contents
file_name: Name of the uploaded SCORM file.
scorm_file: Object containing detailed information about the uploaded file.
scorm_file.status: Current processing status. Possible values:
- processing: File has reached our server and is being prepared for content extraction.
- processed: Preparation is done; file is ready for extraction.
- failed:There were some issues processing the given file.

GET /scorm-files/{scorm_file_id (retrieved from upload api)}/

Tag: Scorm

Fetch file object by id

Response Example status 200

{
    "id": 38,
    "file_name": "some_file_name",
    "user": 1,
    "status": "processed",
    "storage_path": "psi-pratham-softwares-pvt-ltd/scorm-files/38/some_file_name",
    "batch_name": "Lorem ipsuaasdasdasdasdasdasdasdasdasdaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "file_size": 9.21,
    "created_at": "2025-07-18T13:30:33.587545Z",
    "updated_at": "2025-07-18T13:30:34.850737Z",
    "content_extractions": [
        {
            "id": 41,
            "status": "completed",
            "started_at": "2025-07-18T13:30:35.051222Z",
            "finished_at": "2025-07-18T13:30:36.711709Z",
            "file_id": 38,
            "final_output_path": "psi-pratham-softwares-pvt-ltd/scorm-files/38/content_extractions/41/some_file_name.json",
            "file_name": "some_file_name",
            "download_link": "some_downloadable_link_if_available",
            "is_deleted": false,
            "deleted_at": null,
            "deleted_by": null,
            "remarks": "Extraction completed."
        }
    ],
    "last_extraction": {
        "id": 41,
        "status": "completed",
        "started_at": "2025-07-18T13:30:35.051222Z",
        "finished_at": "2025-07-18T13:30:36.711709Z",
        "file_id": 38,
        "final_output_path": "psi-pratham-softwares-pvt-ltd/scorm-files/38/content_extractions/41/some_file_name.json",
        "file_name": "some_file_name",
        "download_link": "some_downloadable_link",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
    },
    "public_url": "public_url_if_given",
    "is_deleted": false,
    "deleted_at": null,
    "deleted_by": null,
    "remark": "File uploaded and processed successfully.",
    "client_ip": "182.156.218.70"
}

Important Parameters:

id: Unique identifier for the SCORM file.
file_name: Name of the SCORM file as uploaded.
user: User ID of the uploader.
status: Current processing status (see status explanations above).
file_size: Size of the file in MB.
created_at: Timestamp when the file was uploaded.
updated_at: Timestamp of the last update to this file record.
content_extractions: List of all extraction process objects associated with this file.
last_extraction: The most recent extraction process object associated with this file.
last_extraction.id: represents id of the extraction. Each extraction process has a unique identifier, which can be used to restart, fetch and other APIs.
public_url: Publicly accessible URL for the file, if available.

DELETE /scorm-files/{scorm_file_id}/

Tag: Scorm

Delete a SCORM file by its ID.

Response Example status 200

{
  "message": "SCORM file with ID 70 deleted successfully."
}

Important Parameters:

scorm_file_id: The unique identifier of the SCORM file to delete.

GET /scorm-files/

Tag: Scorm

Returns a list of SCORM files With Pagination. Every file object will only show last_extraction object

Response Example status 200

{
"count": 15,
"next": "http://127.0.0.1:8000/api/v1/scorm-files/?page=2",
"previous": null,
"results": [
{
    "id": 81,
    "file_name": "some_file_name",
    "user": 3,
    "status": "processed",
    "storage_path": "tech-solutions-inc/scorm-files/81/some_file_name",
    "batch_name": null,
    "file_size": 5.36,   
    "created_at": "2025-07-14T12:38:59.532811Z",
    "updated_at": "2025-07-14T12:39:15.150704Z",
    "last_extraction": {
        "id": 113,
        "status": "dispatched",
        "started_at": "2025-07-14T12:39:16.971930Z",
        "finished_at": null,
        "file_id": 81,
        "final_output_path": null,
        "file_name": "some_file_name",
        "download_link": null,
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": null
    },
    "public_url": null,
    "is_deleted": false,
    "deleted_at": null,
    "deleted_by": null,
    "api_key_name": "My Api Key",
    "remark": "File uploaded and processed successfully."
},
{
    "id": 71,
    "file_name": "some-scorm-package-name-example.zip",
    "user": 6,
    "status": "processed",
    "extraction": null,
    "file_size": 5.43,
    "created_at": "2025-07-10T19:34:24.304996Z",
    "updated_at": "2025-07-10T19:34:34.212750Z",
    "last_extraction": {
        "id": 95,
        "status": "dispatched",
        "started_at": "2025-07-10T19:34:34.205419Z",
        "finished_at": null,
        "file_id": 71,
        "final_output_path": null,
        "file_name": "some-scorm-package-name-example.zip",
        "download_link": null
    },
    "public_url": null
},
{
    "id": 70,
    "file_name": "some-scorm-file-name-example.zip",
    "user": 6,
    "status": "extraction_stalled",
    "extraction": null,
    "file_size": 12.81,
    "created_at": "2025-07-09T22:18:17.692487Z",
    "updated_at": "2025-07-09T22:18:36.539755Z",
    "last_extraction": {
        "id": 94,
        "status": "dispatched",
        "started_at": "2025-07-09T22:18:36.532752Z",
        "finished_at": null,
        "file_id": 70,
        "final_output_path": null,
        "file_name": "some-scorm-file-name-example.zip",
        "download_link": null
    },
    "public_url": "https://cdn.example.com/files/your-file.zip"
},
{
    "id": 69,
    "file_name": "some-scorm-file-name-example.zip",
    "user": 6,
    "status": "failed",
    "extraction": null,
    "file_size": 12.81,
    "created_at": "2025-07-09T22:13:24.210582Z",
    "updated_at": "2025-07-09T22:13:49.462508Z",
    "last_extraction": {
        "id": 93,
        "status": "pending",
        "started_at": null,
        "finished_at": null,
        "file_id": 69,
        "final_output_path": null,
        "file_name": "some-scorm-file-name-example.zip",
        "download_link": null
    },
    "public_url": "https://cdn.example.com/files/your-file.zip"
},
{
    "id": 68,
    "file_name": "some-scorm-package-name-example.zip",
    "user": 6,
    "status": "extraction_stalled",
    "extraction": null,
    "file_size": 5.43,
    "created_at": "2025-07-09T22:12:27.266552Z",
    "updated_at": "2025-07-09T22:12:35.308332Z",
    "last_extraction": {
        "id": 92,
        "status": "dispatched",
        "started_at": "2025-07-09T22:12:35.301237Z",
        "finished_at": null,
        "file_id": 68,
        "final_output_path": null,
        "file_name": "some-scorm-package-name-example.zip",
        "download_link": null
    },
    "public_url": null
},
{
    "id": 66,
    "file_name": "some-scorm-file-name-example.zip",
    "user": 6,
    "status": "content_extraction_completed",
    "extraction": null,
    "file_size": 43.59,
    "created_at": "2025-07-04T13:25:31.293405Z",
    "updated_at": "2025-07-04T13:27:22.710979Z",
    "last_extraction": {
        "id": 86,
        "status": "completed",
        "started_at": "2025-07-04T18:57:29.491990Z",
        "finished_at": "2025-07-04T19:02:13.112184Z",
        "file_id": 66,
        "final_output_path": "content_extractions/86/some-scorm-file-name-example.zip.json",
        "file_name": "some-scorm-file-name-example.zip",
        "download_link": "https://cdn.example.com/content_extractions/86/some-scorm-file-name-example.zip.json"
    },
    "public_url": null
}
]
}

Response Breakdown:

count: Total number of SCORM files available.
next: URL to the next page of results (if paginated).
previous: URL to the previous page of results (if paginated).
results: List of SCORM file objects, each containing:

id: Unique identifier for the SCORM file.
file_name: Name of the SCORM file.
status: Processing status (e.g., completed, in progress, failed).
file_size: Size of the file in MB.
created_at: Upload timestamp.
updated_at: Last update timestamp.
last_extraction: Details about the most recent extraction process.
public_url: Publicly accessible URL for the file (if available).

POST /content-extractions/

Tag: Scorm

Start a new content extraction process for a SCORM file.

Request Example:

{
  "file_id": 67
}

Response Example status 200

{
  "extraction_id": 97,
  "status": "dispatched",
  "started_at": "2025-07-10T20:31:28.833394Z",
  "scorm_file_id": 67,
  "scorm_file": {
    "id": 67,
    "file_name": "a-scorm-file-name-example.zip",
    "user": 3,
    "status": "processed",
    "extraction": null,
    "file_size": 5.39,
    "created_at": "2025-07-08T11:25:40.013225Z",
    "updated_at": "2025-07-10T20:31:28.842398Z",
    "content_extractions": [
      {
        "id": 87,
        "status": "dispatched",
        "started_at": "2025-07-10T07:17:54.854926Z",
        "finished_at": null,
        "file_id": 67,
        "final_output_path": null,
        "file_name": "a-scorm-file-name-example.zip",
        "download_link": null
      },
      {
        "id": 96,
        "status": "dispatched",
        "started_at": "2025-07-10T20:30:27.165909Z",
        "finished_at": null,
        "file_id": 67,
        "final_output_path": null,
        "file_name": "a-scorm-file-name-example.zip",
        "download_link": null
      },
      {
        "id": 97,
        "status": "dispatched",
        "started_at": "2025-07-10T20:31:28.833394Z",
        "finished_at": null,
        "file_id": 67,
        "final_output_path": null,
        "file_name": "a-scorm-file-name-example.zip",
        "download_link": null
      }
    ],
    "last_extraction": {
      "id": 97,
      "status": "dispatched",
      "started_at": "2025-07-10T20:31:28.833394Z",
      "finished_at": null,
      "file_id": 67,
      "final_output_path": null,
      "file_name": "a-scorm-file-name-example.zip",
      "download_link": null
    },
                            "public_url": null
                            },
  "sqs_message_id": "8b9ee33b-6bec-4532-afa9-ac1cb1f00cbf"
}

Important Parameters:

extraction_id: Unique identifier for the extraction process.
status: Status of the extraction process. Possible values:
- pending: Extraction process has just started and is waiting to be dispatched.
- dispatched: Job is sent for extraction and is queued for processing.
- in_progress: Extraction job has started and is being processed by the extractor.
- failed: Extraction process failed due to an error.
- success: Extraction process completed successfully.
started_at: Timestamp when the extraction process started.
scorm_file_id: The ID of the SCORM file for which extraction was started.
scorm_file: The full SCORM file object, including all extractions and last_extraction.
sqs_message_id: Internal message queue ID for tracking the extraction job.

GET /content-extractions/{extraction_id (can be found in scorm-files apis)}/

Content Extraction Details

Response Example: status 200

{
    "id": 39,
    "status": "dispatched",
    "started_at": "2025-07-18T14:05:04.196554Z",
    "finished_at": null,
    "file_id": 36,
    "final_output_path": null,
    "file_name": ".zip",
    "download_link": null,
    "is_deleted": false,
    "deleted_at": null,
    "deleted_by": null,
    "remarks": "Extraction completed."
}

Important Parameters:

id: Unique identifier for the extraction process.
status: Status of the extraction process (see status explanations above).
started_at: Timestamp when the extraction process started.
finished_at: Timestamp when the extraction process finished (if completed).
file_id: The ID of the SCORM file this extraction belongs to.
final_output_path: Path to the extracted output file (relative to storage).
file_name: Name of the original SCORM file.
download_link: Direct link to download the extracted output (if available).

GET /content-extractions/

List Content Extractions

Response Example: status 200

{
    "count": 41,
    "next": "?page=2",
    "previous": null,
    "results": [
        {
        "id": 41,
        "status": "completed",
        "started_at": "2025-07-18T13:30:35.051222Z",
        "finished_at": "2025-07-18T13:30:36.711709Z",
        "file_id": 38,
        "final_output_path": "/file_41.json",
        "file_name": ".zip",
        "download_link": "?signature=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        },
        {
        "id": 40,
        "status": "completed",
        "started_at": "2025-07-18T13:25:20.803125Z",
        "finished_at": "2025-07-18T13:25:22.434268Z",
        "file_id": 37,
        "final_output_path": "/file_40.json",
        "file_name": ".zip",
        "download_link": "?signature=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        },
        {
        "id": 39,
        "status": "completed",
        "started_at": "2025-07-18T12:47:15.883288Z",
        "finished_at": "2025-07-18T12:47:17.516729Z",
        "file_id": 36,
        "final_output_path": "/file_39.json",
        "file_name": ".zip",
        "download_link": "?signature=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        },
        {
        "id": 38,
        "status": "completed",
        "started_at": "2025-07-18T12:46:14.241019Z",
        "finished_at": "2025-07-18T12:46:15.865113Z",
        "file_id": 35,
        "final_output_path": "/file_38.json",
        "file_name": ".zip",
        "download_link": "?signature=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        },
        {
        "id": 37,
        "status": "completed",
        "started_at": "2025-07-17T11:41:51.653675Z",
        "finished_at": "2025-07-17T11:42:03.296077Z",
        "file_id": 34,
        "final_output_path": "/file_37.json",
        "file_name": ".zip",
        "download_link": "?signature=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        }
    ]
    }

Important Parameters:

count: Total number of content extraction objects available.
next: URL to the next page of results (if paginated).
previous: URL to the previous page of results (if paginated).
results: List of content_extraction objects (see above for object details).

POST /content-extractions/{extraction_id}/restart/

Tag: Scorm

Restart a content extraction process by its ID.

Response Example status 200

{
    "message": "Extraction restarted",
    "extraction_id": 39,
    "status": "dispatched",
    "started_at": "2025-07-18T14:05:04.196554Z",
    "scorm_file_id": 36,
    "scorm_file": {
        "id": 36,
        "file_name": ".zip",
        "user": 1,
        "status": "processed",
        "storage_path": "/36/.zip",
        "batch_name": null,
        "file_size": 9.21,
        "created_at": "2025-07-18T12:47:15.047588Z",
        "updated_at": "2025-07-18T12:47:15.747224Z",
        "content_extractions": [
        {
            "id": 39,
            "status": "dispatched",
            "started_at": "2025-07-18T14:05:04.196554Z",
            "finished_at": null,
            "file_id": 36,
            "final_output_path": null,
            "file_name": ".zip",
            "download_link": null,
            "is_deleted": false,
            "deleted_at": null,
            "deleted_by": null,
            "remarks": "Extraction completed."
        }
        ],
        "last_extraction": {
        "id": 39,
        "status": "dispatched",
        "started_at": "2025-07-18T14:05:04.196554Z",
        "finished_at": null,
        "file_id": 36,
        "final_output_path": null,
        "file_name": ".zip",
        "download_link": null,
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remarks": "Extraction completed."
        },
        "public_url": "?token=***",
        "is_deleted": false,
        "deleted_at": null,
        "deleted_by": null,
        "remark": "File uploaded and processed successfully."
    },
    "sqs_message_id": ""
    }

Important Parameters:

message: Confirmation message indicating the extraction was restarted.
extraction_id: The ID of the restarted extraction process.
status: Status of the restarted extraction (typically "dispatched").
started_at: Timestamp when the restarted extraction process began.
scorm_file_id: The ID of the SCORM file associated with this extraction.
scorm_file: The full SCORM file object with updated extraction information.
sqs_message_id: Internal message queue ID for tracking the restarted extraction job.

GET https://api.xtract2ai.com/health/

Tag: Utility

Health check endpoint to verify API is up and running.

Response Example status 200

{
  "status": "healthy",
  "version": "v1",
  "timestamp": "2025-07-14T19:03:50.711280",
  "service": "PSI SCORM Lens API"
}

Important Parameters:

status: Returns healthy if the API is healthy and reachable.
version: The current version of the API.
timestamp: The server time when the health check was performed.
service: The name of the API service.

🔑 API Key Management

👥 User Roles & Access Control

🔗 Webhook Management

📤 Sample Webhook Body

Endpoints

Request Example:

Alternative Request Example (multipart/form-data):

Response Example status 200

Response Example status 200

Response Example status 200

Response Example status 200

Request Example:

Response Example status 200

Content Extraction Details

Response Example: status 200

List Content Extractions

Response Example: status 200

Response Example status 200

Response Example status 200