# API Reference — Argus

Argus file-upload credentials, task submission, task information, and reconstruction products on the overseas gateway.

Canonical: https://developer.realsee.ai/docs/argus/reference
Source: https://developer.realsee.ai/docs/argus/reference.md
Language: en

Use `https://app-gateway.realsee.ai` from your backend. Argus shares the Team-owned Developer app's `/open` scope. Send the raw gateway access token in the `Authorization` header, without a `Bearer` prefix.

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/auth/access_token` | Exchange AK/SK for a gateway token. |
| `GET` | `/open/v1/argus/file/token` | Get temporary credentials for uploading the input ZIP. |
| `POST` | `/open/v1/argus/task/submit` | Submit uploaded object keys and get a `task_code`. |
| `GET` | `/open/v1/argus/task/info` | Query that task and its temporary result download metadata. |

Responses use a gateway envelope. HTTP success alone does not mean business success: require numeric `code: 0` and valid `data` before reading fields. Error responses may have `data: null`.

```json
{
  "code": 0,
  "status": "success",
  "data": {}
}
```

Trace and timing fields may also appear. Do not log the full response: it can contain temporary credentials or download URLs.

## Get a gateway token

`POST /auth/access_token`, with `Content-Type: application/x-www-form-urlencoded`:

```text
app_key=<app_key>&app_secret=<app_secret>
```

| Response data | Type | Meaning |
| --- | --- | --- |
| `access_token` | string | Short-lived raw token for subsequent requests. |
| `expire_at` | integer | Unix token-expiry timestamp in seconds. |

Keep the app secret and token on your backend. Obtain a current token before authenticated requests.

## Get file-upload credentials

`GET /open/v1/argus/file/token` has no business query parameters or request body.

```http
GET /open/v1/argus/file/token
Host: app-gateway.realsee.ai
Authorization: <access_token>
```

The upload lease is returned directly under `data`:

| Field | Type | Meaning |
| --- | --- | --- |
| `tmpSecretId`, `tmpSecretKey`, `sessionToken` | string | Temporary storage credentials. Do not persist or log them. |
| `bucket`, `region` | string | Storage destination. |
| `prefix` | string | Authorized object-key prefix. |
| `expire`, `ttl` | number | Credential-expiry information and lifetime returned by the service. These are distinct from the task result's `expiration_timestamp`. |

Additional provider fields can be present. Pass the complete lease to the upload adaptor; the [Quickstart](https://developer.realsee.ai/docs/argus/quickstart) uses `@realsee/universal-uploader@0.1.1` and the overseas AWS adaptor.

Package multiple 2:1 equirectangular panoramas **or** multiple 1:1 pinhole images in one ZIP, with images at the root. Use one image type per batch. Upload before submitting a task. Retain the uploader's full `objectPath`, including its prefix.

## Submit a task

`POST /open/v1/argus/task/submit`, with `Content-Type: application/json`:

```http
POST /open/v1/argus/task/submit
Host: app-gateway.realsee.ai
Authorization: <access_token>
Content-Type: application/json

{
  "private_cos_keys": ["<full_uploaded_object_key>"],
  "title": "My reconstruction"
}
```

| Request field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `private_cos_keys` | string[] | Yes | Nonempty array of full uploaded object keys. Pass the full key for the input ZIP. Keys must belong to the same granted resource directory. |
| `title` | string | Yes | Nonempty task title. |

There is no input-type parameter in this request. Do not send storage URLs instead of object keys.

A successful response includes:

```json
{
  "code": 0,
  "status": "success",
  "data": {
    "task_code": "<task_code>"
  }
}
```

Persist `task_code` as the task reference. Submission is not idempotent. Do not automatically retry when a timeout or lost response leaves the outcome unknown; the task may already exist.

## Query task information

`GET /open/v1/argus/task/info?task_code=<task_code>`:

```http
GET /open/v1/argus/task/info?task_code=<task_code>
Host: app-gateway.realsee.ai
Authorization: <access_token>
```

`task_code` is a required nonempty query parameter. The response's `data` fields are:

| Field | Type | Meaning |
| --- | --- | --- |
| `status` | integer | `0` queued, `1` processing, `2` task succeeded, `3` task failed. |
| `output_url` | string | Temporary URL for `output.zip` after success; empty while work is pending. |
| `expiration_timestamp` | integer | Unix expiration timestamp for that download URL, in seconds. |
| `error_message` | string | Failure detail; usually empty when the task has not failed. |
| `create_timestamp`, `modify_timestamp` | integer | Task creation and last-update timestamps. |

Continue queries for `0` or `1`. For `2`, require a nonempty `output_url` and download before `expiration_timestamp`. For `3`, stop and handle the failure. Retain the task code when a local waiting deadline expires; do not create another task merely to resume waiting.

## Reconstruction products

| File in `output.zip` | Product |
| --- | --- |
| `output.json` | Required manifest, image-name mapping, relative product paths, and algorithm result status. |
| `depth/*_depth.exr` | Per-image 32-bit floating-point depth maps in meters. |
| `pointcloud/merged.glb` | Merged point cloud; right-handed, Y-up coordinates. |
| `pose/*_pose.json` | Per-image world-to-camera rotation and translation. |
| `intrinsics/*_intrinsics.json` | Optional camera calibration; interpret the actual returned model. |

Task success does not guarantee that every input image reconstructed. Read `output.json.status`: `success`, `partial`, or `error`. A partial result identifies unsuccessful images in `missing_ids`; map IDs back to filenames with `name_mapping`.

See [Outputs and Result Handling](https://developer.realsee.ai/docs/argus/outputs) for full semantics and validation. A GLB point cloud is not a complete Realsee VR project or Five SDK Work payload. [Pano-to-VR](https://developer.realsee.ai/docs/pano-to-vr) uses a separate API for that workflow.

Do not treat a temporary result URL as permanent storage or assume a fixed seven-day lifetime. Store downloaded files under your own access controls. Keep AK/SK, tokens, temporary upload credentials, result URLs, and raw task diagnostics out of frontend logs and analytics.