Getting Started

This page gets you to a successful request as quickly as possible. For the full end-to-end import, including reading the job result, continue to the First Import Walkthrough.

Before you begin

You need three things:

A base URL for the environment you’re integrating with.
An API key for that environment — see Authentication & API Keys.
An HTTP client — curl, Postman, or your own code.

The shape of every request

Every Praedico Integration Platform request shares the same essentials:

HTTPS only, to the environment base URL.
A version prefix of v2 on the path (for example v2/assets).
An authentication header (Api-Key).
For imports, a JSON body and Content-Type: application/json.

Make your first call

The quickest call that proves your key works is a job status check. Asking for a non-existent job returns 404, which is still a successful, authenticated round-trip.

Set your base URL and key as shell variables:

export BASE_URL="https://<api-host>/<your-tenant-prefix>"
# Send your API key exactly as issued — a single string of the form <key>_<id>
export API_KEY="<your-api-key>"

Call the job status endpoint:

curl -i "$BASE_URL/v2/status/1" \
  -H "Api-Key: $API_KEY"

Read the result:
- 401 Unauthorized → your key/header is wrong. See Authentication.
- 404 Not Found → your key works; job 1 just doesn’t exist. You’re ready to import.
- 200 OK → your key works and job 1 exists; you’ll get a job status document back.

Send a real import

Imports are asynchronous. You POST data and get back a job to poll. Here’s a minimal asset import:

curl
What you get back

curl -i -X POST "$BASE_URL/v2/assets" \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "External-Id",
      "subAreaId": "004",
      "name": "Asset Name",
      "status": "A",
      "assetCategoryId": "TRACK-RAIL",
      "assetTypeId": "OBJ007",
      "shapeType": "LineString"
    }
  ]'

A 202 Accepted with a job document:

{
  "id": 1234,
  "importJobType": "Asset",
  "importJobStatus": "Pending",
  "statusUrl": "/v2/status/1234",
  "output": null
}

Poll statusUrl until importJobStatus is Succeeded, PartiallySucceeded, or Failed.