Dataloader

Notes:

Public API v1 is currently in feature preview and as such documentation for this feature is still work in progress

Data Loader endpoints are used to upload data for processing.

Upload

POST /dataloader/upload

The upload endpoint is used to submit data for processing.

• Two request formats are supported on the same path:

  • application/json for direct CSV/JSON packet uploads
  • multipart/form-data for CSV/JSON file uploads

• CSV data and JSON data can be submitted using either request format.

  • For multipart/form-data, CSV or JSON is provided in the uploaded file.
  • For application/json, CSV or JSON is provided in the data property.

Upload request (application/json)

• The request content type is application/json.
• entityId is required and identifies the Data Loader entity to load.
  • The value from GET /connections is used.
  • Raw integer entity keys are not supported.
• data is required and contains the payload to be processed.
  • For JSON uploads, a JSON array of flat objects is provided.
  • For CSV uploads, a CSV string is provided.

Example: JSON rows

Example request (application/json):

curl --request POST \
  --url https://xpna.app/api/public/v1/dataloader/upload \
  --header "x-api-key: <api-key>" \
  --header "Content-Type: application/json" \
  --data '{"entityId":"<entity-id-from-connections>","data":[{"Account":"Sales","Amount":100}]}'

{
  "entityId": "<entity-id-from-connections>",
  "data": [
    {
      "Account": "Sales",
      "Amount": 100
    }
  ]
}

Example: CSV string

Example request (application/json with CSV string):

curl --request POST \
  --url https://xpna.app/api/public/v1/dataloader/upload \
  --header "x-api-key: <api-key>" \
  --header "Content-Type: application/json" \
  --data '{"entityId":"<entity-id-from-connections>","data":"Account,Amount\\nSales,100\\n"}'

{
  "entityId": "<entity-id-from-connections>",
  "data": "Account,Amount\nSales,100\n"
}

Upload request (multipart/form-data)

• The request content type is multipart/form-data.

Key	Value
entityId	The entityId from GET /connections that identifies the Data Loader entity to load.
file	The uploaded file containing either CSV or JSON data in the format required by the Data Loader definition created for this connection.

Raw integer entity keys are not supported.

Example request (multipart/form-data):

curl --request POST \
  --url https://xpna.app/api/public/v1/dataloader/upload \
  --header "x-api-key: <api-key>" \
  --form "entityId=<entity-id-from-connections>" \
  --form "file=@./data.csv"

Upload response

• A 200 OK response is returned when the upload is accepted.
• data.entityId is the identifier of the entity being loaded.
• data.syncId is the identifier for the upload job and can be used to check status.
• data.message is a human-readable status message.

Note:

The syncId returned in the upload response is used with GET /connections/sync/{syncId}/status.

If an invalid entityId value is provided (or the workspace cannot be resolved), a 200 OK response is still returned and the message field indicates the issue.

{
  "data": {
    "entityId": "<entity-id-from-connections>",
    "syncId": "9c4a7e1e9c58432a9f9e3d76c9f12e4d",
    "message": "Data upload triggered"
  },
  "meta": {
    "apiVersion": "1.0",
    "requestId": "0HMP7E6LQJ6J3:00000001",
    "correlationId": "9c4a7e1e9c58432a9f9e3d76c9f12e4d",
    "workspaceIdentifier": "demo",
    "timestamp": "2026-02-03T05:16:02.000Z"
  }
}