📕 Contents

About this guide

This guide is provided to the Vueron Technology Customer as a reference for using the API Annotation feature.

This document may be distributed internally for development and integration purposes only.
All other reproductions are prohibited without written permission from Vueron Technology.

Vueron Technology makes no warranties, expressed or implied, regarding this documentation.
The information contained herein is subject to change without notice.

Data Processing Addendum for API (DPA-API)

Overview

The API Annotation feature allows users to perform annotation on PCD (Point Cloud Data) files by calling REST APIs.

By issuing an API Key, users can integrate annotation capabilities directly into their own pipelines and workflows.

This feature supports:

Annotation execution via REST APIs

Single-file annotation for immediate results (Sync Annotation)

Batch annotation for large datasets (Bulk Annotation, up to 1,000 PCD files)

Progress monitoring for batch jobs

Secure result delivery via time-limited presigned URLs

Track session support to maintain continuous Track IDs across frames, ensuring object tracking consistency

Optional per-frame vehicle position and orientation (frame meta) for bulk annotation

Track Session & Track ID

Track Session

A Track Session is a tracking context that maintains object identity across multiple frames, so that the system can recognize and continuously track the same object over time.

A track session is identified by a session key. Every annotation request runs inside a track session, which is selected as follows:

If sessionKey is included in the request, the track session with that key is used. It is created on first use.

If sessionKey is omitted, the default track session of the API Key is used.

Multiple track sessions can be active at the same time under one API Key, for example one per driving sequence. The number of concurrently active track sessions is limited per tenant, and exceeding the limit returns resultCode 49423.

A track session expires after a period of inactivity (1 hour by default). Each request that uses the session extends its expiration.

Track ID

A Track ID is a unique identifier assigned to an object and maintained across consecutive frames. Within a track session, the same object detected in multiple frames retains the same Track ID, ensuring tracking continuity.

Important Notes

Tracking is always performed within a request. useSession controls whether Track IDs continue into the next request. With true, the track session is kept after the request completes, so the next request continues the same Track IDs. With false (default), the track session is deleted once the request completes, and the next request starts with new Track IDs. For Sync Annotation, this means each request is tracked independently unless useSession is true. For Bulk Annotation, frames within one job are always tracked together, and useSession decides whether the next job continues from them.

Only one request can run in a track session at a time. Sending another request with the same session key while a request is in progress returns resultCode 1409.

Bulk Annotation processes the presigned URLs in the order given. To ensure accurate Track ID generation, the presigned URLs must be arranged in chronological frame order.

Calling the Delete Track Session API deletes the track session. After deletion, a new track session is created on the next request, and object continuity with previously processed frames is no longer maintained.

API Key Issuance

To use the API Annotation feature, an API Key must be issued in advance.

⚠️ Note:
The number of API Keys that can be issued is limited to 5 per seat (user).
If you reach the limit, you must delete an existing API Key before issuing a new one.

Issuance Steps

Navigate to the API Keys screen.

Click Create New Key.

Enter the following information:

Key name

Expiration date

Once the key is created, the Secret Key is displayed only once.

The user must copy and securely store the Secret Key.

The issued Secret Key is the API Key and must be included in the HTTP header for all API requests.

Usage Flow

The recommended usage flow for API Annotation is as follows:

Retrieve available modelings for annotation

Retrieve available class list for annotation

Execute annotation

Sync Annotation (single file)

Bulk Annotation (multiple files)

(For Bulk Annotation)

Retrieve bulk annotation request list

Check processing status

After bulk processing is completed

Receive result information via callback

Download result files using the presigned URL

API Response Format

All API Annotation endpoints return the same response envelope, regardless of success or failure.

{
    "trID": "20260116100653573276",
    "resultCode": "0200",
    "resultMsg": "APIAnnotationBulk OK",
    "resultData": {}
}

Relationship between the HTTP status code and `resultCode`

The HTTP status code and resultCode are not independent values. Both are derived from a single
internal result code, and resultCode always carries equal or finer-grained information than the
HTTP status code.

Internal code range	HTTP status code	`resultCode`	Example
Below `1000` (general status)	The code itself	`"1"` + the code	`400` → HTTP `400`, `resultCode` `"1400"`
`1000` or above (Vueron-specific error)	code % 1000	The code itself	`41423` → HTTP `423`, `resultCode` `"41423"`

Because of this rule, a single HTTP status code can map to several different resultCode values.
For example, HTTP 423 is returned for three distinct conditions, which can only be told apart by
resultCode: annotation quota exceeded (41423), expired contract (45423), and track session
quota exceeded (49423).

⚠️ Note:
Always branch your error handling on resultCode, not on the HTTP status code.
The HTTP status code alone is not sufficient to identify the cause of a failure.

Common `resultCode` values

HTTP	`resultCode`	Meaning
200	`0200`	Success
400	`1400`	Bad Request — missing `X-Tenant-ID` or `X-Header-API-Key` header, malformed API Key, invalid request body, or a failed field validation
401	`1401`	Unauthorized — the API Key is invalid
403	`1403`	Forbidden — the API Key is inactive or expired
404	`1404`	Not Found — no matching API Key, modeling, or bulk annotation job
409	`1409`	Conflict — another request using the same track session is already in progress
423	`41423`	Annotation quota exceeded. `resultMsg` contains a JSON payload with `used`, `reward`, and `limit`
423	`45423`	The tenant contract has expired
423	`49423`	Concurrent track session quota exceeded. `resultMsg` contains a JSON payload with `used` and `limit`
500	`1500`	Internal server error

⚠️ Note:
When HTTP 500 is returned, resultMsg is always masked as "Internal Server Error".
Report the trID from the response when contacting support so the request can be traced.

Because Bulk Annotation is processed asynchronously, a 0200 response only means the request was
accepted. Failures that occur during actual processing are not reported as HTTP error codes — check
them through the Get Bulk-Annotation Status API.

Provided APIs

Get Default Modelings

Retrieves the list of default system modelings available for annotation.

The returned modelings are used as input for annotation requests.

Get Default Class List

Retrieves:

Supported object classes for annotation

Default confidence values for each class

Sync Annotation

Performs annotation for a single PCD file.

One PCD file per request

Annotation result is returned synchronously in the API response

Request Body

Field	Type	Required	Description
`modelingID`	string	Yes	Modeling ID from Get Default Modelings
`presignedURL`	string[]	Yes	Presigned URL of the PCD file. Only the first URL is used
`distance`	number	No	Detection range in meters. `0` or omitted uses the default (`70`)
`confidence`	object	No	Confidence threshold per class, keyed by class name (case-insensitive). Omitted classes and `0` use the default confidence from Get Default Class List. Values outside the allowed range of a class are clamped
`useSession`	boolean	No	Keep the track session after the request completes. Default `false`
`sessionKey`	string	No	Track session key, 1 to 37 alphanumeric characters (`-` and `_` allowed). Omitted uses the default track session of the API Key

Response

resultData contains the annotation result of the file in label JSON format. Each detected object appears in objects with its class, and in figures with its 3D box geometry, confidence, and Track ID. The same format is used for each frame in the Bulk Annotation result file.

Bulk Annotation

Performs annotation for multiple PCD files (up to 1,000 files) using batch processing.

Asynchronous processing

A transaction ID (trID) is issued in the response

Annotation results are delivered via the specified callback URL

Optionally, per-frame vehicle position and orientation can be provided through frameMeta (see Frame Meta)

Request Body

Field	Type	Required	Description
`modelingID`	string	Yes	Modeling ID from Get Default Modelings
`presignedURL`	string[]	Yes	Presigned URLs of the PCD files in frame order, 1 to 1,000
`callbackURL`	string	Yes	URL that receives the result when the job completes
`distance`	number	No	Detection range in meters. `0` or omitted uses the default (`70`)
`confidence`	object	No	Confidence threshold per class, keyed by class name (case-insensitive). Omitted classes and `0` use the default confidence from Get Default Class List. Values outside the allowed range of a class are clamped
`useSession`	boolean	No	Keep the track session after the job completes. Default `false`
`sessionKey`	string	No	Track session key, 1 to 37 alphanumeric characters (`-` and `_` allowed). Omitted uses the default track session of the API Key
`frameMeta`	object[]	No	Per-frame vehicle position and orientation. See Frame Meta

⚠️ Note:
For bulk annotation requests, it is recommended to use presigned URLs with a sufficiently long expiration time (e.g., around 1 hour) to ensure stable processing. If the presigned URL credential expires while the job is running, the remaining frames fail with presigned URL credential expired.
The system interprets the order of presigned URLs in the request as the frame sequence.
To ensure accurate Track ID generation, the presigned URLs must be arranged in the correct chronological frame order.
If the frame order is incorrect, Track IDs may not be generated accurately.
When frameMeta is used, its entries must follow the same order as the presigned URLs.

Frame Meta

frameMeta is an optional array that carries the position and orientation of the vehicle at the moment each PCD file was captured. Each entry is paired with the presigned URL at the same index, so the number of entries must equal the number of presigned URLs. If it is omitted, the request is processed in the same way as before, without using vehicle motion information. frameMeta is ignored in Sync Annotation requests.

Each entry must contain timestamp and either gps or pose.

Fields

Field	Type	Unit	Description
`timestamp`	integer	milliseconds	Capture time of the frame
`gps.latitude`	number	degrees (WGS84)	Latitude
`gps.longitude`	number	degrees (WGS84)	Longitude
`gps.heading`	number	degrees	Heading
`pose.x`, `pose.y`, `pose.z`	number	meters	Position
`pose.qx`, `pose.qy`, `pose.qz`, `pose.qw`	number		Orientation as a quaternion

Required fields by source

Source	Required fields
`gps`	`latitude`, `longitude`, `heading`
`pose`	`x`, `y`, `z`, `qx`, `qy`, `qz`, `qw`

⚠️ Note:
At least 2 entries are required.
The interval between consecutive timestamps must be constant.
Use the same source (gps or pose) for every entry in a request.
A request that violates these rules is rejected with HTTP 400 (resultCode 1400).

Examples

GPS:

"frameMeta": [
    {"timestamp": 1735689600000, "gps": {"latitude": 37.497900, "longitude": 127.027600, "heading": 350.0}},
    {"timestamp": 1735689600100, "gps": {"latitude": 37.497908, "longitude": 127.027601, "heading": 351.0}}
]

Pose:

"frameMeta": [
    {"timestamp": 1735689600000, "pose": {"x": 0.0, "y": 0.0, "z": 0.0, "qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0}},
    {"timestamp": 1735689600100, "pose": {"x": 1.0, "y": 0.0, "z": 0.0, "qx": 0.0, "qy": 0.0, "qz": 0.0, "qw": 1.0}}
]

Get Bulk-Annotation Status

Retrieves the processing status of a bulk annotation request.

Requires the trID issued during the bulk annotation request

Used to monitor progress until completion

Status Values

Status	Description
`AnnotationInProgress`	The bulk annotation job is currently in progress.
`AnnotationSuccess`	The annotation process has completed successfully.
`AnnotationFail`	The annotation process has failed.
`PostProcessSuccess`	The bulk annotation job completed successfully and the result files have been generated and returned.
`PostProcessFail`	The bulk annotation job failed during the finalization or result generation process.

Response

Field	Type	Description
`state`	string	One of the status values above
`startedAt`	datetime	Time the job was accepted
`endedAt`	datetime	Time the job finished
`totalCount`	integer	Number of requested frames
`successCount`	integer	Number of frames annotated successfully
`failCount`	integer	Number of frames that failed
`frames`	object[]	Per-frame status. Each entry has `frameSeq` (1-based order in the request), `filePath` (the presigned URL), `state` (`Success` or `Fail`), and `failLog` (`resultCode`, `resultMsg`) for failed frames

⚠️ Note:
Per-frame data in frames is kept for about 1 hour after the job finishes when every frame succeeded, and for 30 days when at least one frame failed, so that the failure reason of each frame can be checked. After that period, frames is returned empty while the job summary remains available.

Get Bulk-Annotation List

Retrieves the list of bulk annotation requests associated with the API Key.

Useful for monitoring and managing annotation job history

Each item contains trID, state, startedAt, endedAt, totalCount, successCount, and failLog when the job failed

Get API Key Usage

Gets the usage information for the current API Key.

Use this to monitor the total quota and current usage

Includes the number of currently active track sessions

Response

Field	Type	Description
`totalUsageLimit`	integer	Annotation quota of the tenant
`totalUsage`	integer	Annotation usage of the tenant across all API Keys
`keyUsage`	integer	Annotation usage of this API Key
`sessionCount`	integer	Number of currently active track sessions

Delete Track Session

Deletes a track session.

Once deleted, object continuity across previously processed frames is no longer maintained

The next request with the same session key starts a new session

Use this when you need to reset the tracking context or start a new tracking sequence

Bulk Result Delivery & Download

When a bulk annotation job is completed:

The system sends a request to the callback URL specified in the bulk annotation request.

The callback payload includes a presigned URL for downloading the result file.

The presigned URL:

Allows downloading the result file

Expires 1 hour after issuance

The result file is a zip archive containing one JSON file per frame, named {frameSeq}.json (1.json, 2.json, ...). Each JSON file uses the same label JSON format as the Sync Annotation response. For a frame that failed, objects and figures are empty and description contains the failure reason.

callBack RequestBody Example

{
    "trID": "20260116060718590774",
    "resultURL": "<presignedURL>",
    "fileSize": 36645
}

Vueron Technology Co., Ltd.

Website www.vueron.com
Support sales@vueron.com

Headquaters

19F, Gangnam-daero 311, Seocho-gu, Seoul, Korea (06628)

US Office

2665 N 1st St. Suite 110, San Jose, CA 95134, United States

Europe Office

355-3F, Herzogspitalstrasse 24, 80331 Munich, Germany

API Annotation User Guide

📕 Contents#

About this guide#

Overview #

Track Session & Track ID #

Track Session#

Track ID#

Important Notes#

API Key Issuance #

Issuance Steps#

Usage Flow #

API Response Format #

Relationship between the HTTP status code and resultCode#

Common resultCode values#

Provided APIs #

Get Default Modelings #

Get Default Class List #

Sync Annotation #

Request Body#

Response#

Bulk Annotation #

Request Body#

Frame Meta #

Fields#

Required fields by source#

Examples#

Get Bulk-Annotation Status #

Status Values#

Response#

Get Bulk-Annotation List #

Get API Key Usage #

Response#

Delete Track Session #

Bulk Result Delivery & Download #

callBack RequestBody Example#

Vueron Technology Co., Ltd.#

Headquaters#

US Office#

Europe Office#

📕 Contents

About this guide

Overview

Track Session & Track ID

Track Session

Track ID

Important Notes

API Key Issuance

Issuance Steps

Usage Flow

API Response Format

Relationship between the HTTP status code and `resultCode`

Common `resultCode` values

Provided APIs

Get Default Modelings

Get Default Class List

Sync Annotation

Request Body

Response

Bulk Annotation

Request Body

Frame Meta

Fields

Required fields by source

Examples

Get Bulk-Annotation Status

Status Values

Response

Get Bulk-Annotation List

Get API Key Usage

Response

Delete Track Session

Bulk Result Delivery & Download

callBack RequestBody Example

Vueron Technology Co., Ltd.

Headquaters

US Office

Europe Office