📕 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

Track Session & Track ID

Track Session

A Track Session is a tracking context associated with an API Key.
It maintains object identity across multiple frames so that the system can recognize and continuously track the same object over time.

Each API Key can have an active track session, and all Track IDs are generated within the scope of that session.
The track session can be reset by calling the Delete Session Key API, which initializes a new tracking context for the API Key.

Track ID

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

Important Notes

When using Sync Annotation, enabling the useSession option generates Track IDs based on the current API Key’s track session, ensuring object tracking continuity across frames.

Bulk Annotation always generates Track IDs based on the current active track session.
To ensure accurate Track ID generation, presigned URLs must be requested in the correct chronological sequence order.

Calling the Delete Session Key API resets the track session associated with the API Key.
After deletion, a new track session will be created upon the next request, and object continuity with previously processed frames will no longer be 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

When useSession is enabled, Track IDs are generated based on the current track session to maintain object continuity across frames

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

Track IDs are generated based on the current active track session to maintain object continuity across frames

⚠️ 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.
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.

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.

Get Bulk-Annotation List

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

Useful for monitoring and managing annotation job history

Get API Key Usage

Gets the usage information for the current API key.

Use this to monitor the total quota and current usage of the API key

Useful for tracking consumption and remaining limits

Includes information about the current TrackSession and its expiration time

Delete Session Key

Deletes the track session associated with the API Key.

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

Subsequent use of TrackSession will start a new session

Use this when you need to reset 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

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 #

Bulk Annotation #

Get Bulk-Annotation Status #

Status Values#

Get Bulk-Annotation List #

Get API Key Usage #

Delete Session Key #

Bulk Result Delivery & Download #

callBack RequestBody Example#

Vueron Technology Co., Ltd.#

Headquaters#

US Office#

Europe Office#