Jobs & File Uploads¶

POST /api/job/{trigger}
GET  /api/job/{trigger}
GET  /api/job?jobs=[]

Authentication required.

The Jobs API handles asynchronous operations - primarily bulk data imports via file upload, and long-running computations like inventory planning recalculation.

Supported Triggers¶

Data Upload Triggers¶

Trigger	Description	File Type
`forecast`	Upload forecast data	XLSX / CSV
`procurement`	Upload purchase order data	XLSX / CSV
`demand`	Upload sales order data	XLSX / CSV
`manufacturing`	Upload manufacturing order data	XLSX / CSV
`inventory`	Upload inventory data	XLSX / CSV
`bill-of-materials`	Upload BOM data	XLSX / CSV
`item-master`	Upload item master data	XLSX / CSV
`customer-master`	Upload customer master data	XLSX / CSV
`supplier-master`	Upload supplier master data	XLSX / CSV
`warehouse-master`	Upload warehouse master data	XLSX / CSV
`unit-master`	Upload unit of measure data	XLSX / CSV
`external-item-master`	Upload external item mappings	XLSX / CSV
`supplier-allocation`	Upload supplier allocation data	XLSX / CSV

Computation Triggers¶

Trigger	Description
`inventory-planning`	Recalculate inventory planning settings and suggestions

POST - Upload File or Trigger Job¶

POST /api/job/{trigger} HTTP/1.1
Content-Type: multipart/form-data
X-XSRF-TOKEN: <csrf>

file=<binary file data>

Example - Upload Forecast File¶

CSRF=$(grep csrf_access_token cookies.txt | awk '{print $NF}')

curl -b cookies.txt -X POST https://acme.knosc.com/api/job/forecast \
  -H "X-XSRF-TOKEN: $CSRF" \
  -F "file=@forecast-q2-2024.xlsx"

Response¶

{
  "message": "File uploaded. Processing started.",
  "job_id": "forecast-upload-abc123",
  "status": "queued"
}

Trigger Job (No File)¶

For computation triggers (e.g., inventory-planning):

curl -b cookies.txt -X POST https://acme.knosc.com/api/job/inventory-planning \
  -H "X-XSRF-TOKEN: $CSRF"

If a job of this type is already running, the request is queued rather than rejected.

GET - Download Uploaded File¶

GET /api/job/{trigger} HTTP/1.1

Downloads the most recently uploaded file for the given trigger type.

curl -b cookies.txt "https://acme.knosc.com/api/job/forecast" \
  -o latest-forecast.xlsx

GET - Check Job Status¶

GET /api/job?jobs=[{"trigger": "forecast", "job_id": "forecast-upload-abc123"}] HTTP/1.1

Query Parameters¶

Parameter	Type	Required	Description
`jobs`	JSON array	Yes	List of job objects to check

Each job object:

{ "trigger": "forecast", "job_id": "forecast-upload-abc123" }

Response¶

{
  "jobs": [
    {
      "trigger": "forecast",
      "job_id": "forecast-upload-abc123",
      "status": "completed",
      "rows_processed": 1200,
      "errors": [],
      "completed_at": "2024-03-15T10:45:00Z"
    }
  ]
}

Job Status Values¶

Status	Description
`queued`	Waiting to start
`running`	Currently processing
`completed`	Finished successfully
`failed`	Processing failed - check `errors`

Access Control¶

Upload permissions follow granular privilege filters. Users without the appropriate privilege for a trigger type will receive 403 User.NotPrivileged.

Python Example¶

import json

csrf = session.cookies.get("csrf_access_token")

# Upload a file
with open("forecast-q2.xlsx", "rb") as f:
    r = session.post(
        "https://acme.knosc.com/api/job/forecast",
        headers={"X-XSRF-TOKEN": csrf},
        files={"file": ("forecast-q2.xlsx", f, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")}
    )

job_id = r.json()["job_id"]

# Poll for status
r = session.get(
    "https://acme.knosc.com/api/job",
    params={"jobs": json.dumps([{"trigger": "forecast", "job_id": job_id}])}
)
print(r.json()["jobs"][0]["status"])

Upload File Templates¶

Download blank upload templates:

curl -b cookies.txt "https://acme.knosc.com/api/templates"

Returns template file links for each supported upload type.