API

Overview
Base URL
Authentication
API Key Authentication Security Recommendations
API Workflow
Endpoints
Health Check Upload Scan Start Processing Get Scan Status
Scan Status Values
Error Handling
End-to-End Example
Notes

Overview

The IDS Halo Data Ingestion and Processing API is designed for server-to-server integration scenarios where external systems need to:

Upload scan files in E57 format
Initiate processing workflows on uploaded scans
Monitor processing status through polling

All requests are authenticated using API keys. Data is automatically associated with the workspace linked to the provided API key — no workspace identifier is needed in requests.

Base URL

https://idshalo.asets.io/api/v1

Sandbox environments may be provided for testing purposes.

Authentication

API Key Authentication

All requests (except the health check) must include an API key via the Authorization header:

Authorization: Bearer <API_KEY>

Key characteristics:

Property

Detail

Scope

API keys are issued per workspace

Workspace binding

Each request is automatically scoped to the workspace tied to the key

Workspace ID required?

No — workspace context is inferred from the key

Sensitivity

API keys should be treated as sensitive credentials

Security Recommendations

Practice

Description

Secure storage

Store API keys in backend systems only

No client exposure

Never expose API keys in client-side applications

Key rotation

Rotate keys periodically

Revocation

Revoke keys immediately if compromised

API Workflow

The standard integration flow follows four steps:

All requests (except the health check) must include an API key via the Authorization header:

┌──────────────┐     ┌──────────────┐      ┌──────────────┐      ┌─────────────┐     
│  1. Upload   │────▶│ 2. Receive   │────▶│ 3. Trigger   │────▶│ 4. Poll     |
│ 
│  E57 file    │     │    scanId    │      │  processing  │      │    status   |
│ 
└──────────────┘     └──────────────┘      └──────────────┘      └─────────────┘ 
   POST /scans          Response            POST /scans/          GET /scans/ 
                                            {scanId}/process      {scanId}

Sandbox environments may be provided for testing purposes.

Endpoints

Health Check

Check API availability. No authentication required.

GET /health

Response 200 OK

{
  "status": "ok",
  "timestamp": "2026-01-21T10:15:00Z"
}

Response 503 Service Unavailable

{
  "status": "degraded",
  "message": "Service temporarily unavailable"
}

Upload Scan

Upload an E57 scan file and create a new scan resource.

POST /scans

Headers:

Authorization: Bearer <API_KEY> 
Content-Type: multipart/form-data

Form Data:

Field

Type

Required

Description

file

binary

Yes

E57 scan file

Example Request:

curl -X POST "https://idshalo.asets.io/api/v1/scans" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@scan.e57"

Response 201 Created

{
  "scanId": "scan_abc123",
  "fileName": "scan.e57",
  "status": "uploaded",
  "createdAt": "2026-01-21T10:20:00Z"
}

Error Responses

Code

Description

400

Invalid request or missing file

401

Unauthorized — invalid or missing API key

404

Unsupported file type (only E57 is accepted)

409

Internal server error

Start Processing

Trigger processing for a previously uploaded scan.

POST /scans/{scanId}/process

Headers:

Authorization: Bearer <API_KEY>

Path Parameters:

Parameter

Type

Description

scanId

string

The scan ID returned from the upload endpoint

Example Request:

curl -X POST "https://idshalo.asets.io/api/v1/scans" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@scan.e57"

Response 201 Created

{
  "scanId": "scan_abc123",
  "fileName": "scan.e57",
  "status": "uploaded",
  "createdAt": "2026-01-21T10:20:00Z"
}

Error Responses

Code

Description

400

Scan is not ready for processing

401

Unauthorized — invalid or missing API key

404

Scan not found

409

Processing has already been started for this scan

Get Scan Status

Retrieve the current state of a scan, including processing progress.

GET /scans/{scanId}

Headers:

Authorization: Bearer <API_KEY>

Path Parameters:

Parameter

Type

Description

scanId

string

The scan identifier

Example Request:

curl -X GET "https://idshalo.asets.io/api/v1/scans/scan_abc123" \
  -H "Authorization: Bearer <API_KEY>"

Response 201 Created

{
  "scanId": "scan_abc123",
  "fileName": "scan.e57",
  "status": "processing",
  "progress": 42,
  "createdAt": "2026-01-21T10:20:00Z",
  "updatedAt": "2026-01-21T10:25:00Z"
}

Scan Status Values

Status

Description

uploaded

File has been uploaded successfully and is awaiting processing

processing

Scan processing is currently in progress

completed

Processing has finished successfully

failed

Processing encountered an error and did not complete

Error Handling

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "error_code",
    "message": "Description of the error"
  },
  "requestId": "req_abc123xyz"
}

The requestId field can be used when contacting support to help diagnose issues.

End-to-End Example

A complete integration walkthrough from upload to completion.

Step 1 — Upload the scan file

curl -X POST "https://idshalo.asets.io/api/v1/scans" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "file=@scan.e57"

{
  "scanId": "scan_abc123",
  "fileName": "scan.e57",
  "status": "uploaded",
  "createdAt": "2026-01-21T10:20:00Z"
}

Step 2 — Start processing

curl -X POST "https://idshalo.asets.io/api/v1/scans/scan_abc123/process" \
  -H "Authorization: Bearer <API_KEY>"

{
  "scanId": "scan_abc123",
  "jobId": "job_xyz789",
  "status": "processing",
  "submittedAt": "2026-01-21T10:21:00Z"
}

Step 3 — Poll for status

curl -X GET "https://idshalo.asets.io/api/v1/scans/scan_abc123" \
  -H "Authorization: Bearer <API_KEY>"

{
  "scanId": "scan_abc123",
  "fileName": "scan.e57",
  "status": "completed",
  "progress": 100,
  "createdAt": "2026-01-21T10:20:00Z",
  "updatedAt": "2026-01-21T10:35:00Z"
}

Notes

Only the E57 file format is supported in this version.
Processing is asynchronous — the `POST /scans/{scanId}/process` endpoint returns immediately with a `202 Accepted` response.
Clients should poll the `GET /scans/{scanId}` endpoint to monitor progress until the status reaches `completed` or `failed`.
Large file uploads may require extended time depending on network conditions.

Overview

Base URL

Authentication

API Key Authentication

Security Recommendations

API Workflow

Endpoints

Health Check

Upload Scan

Start Processing

Get Scan Status

Scan Status Values

Error Handling

End-to-End Example

Step 1 — Upload the scan file

Step 2 — Start processing

Step 3 — Poll for status

Notes

Stay updated with

our latest news!