# Upload

## Upload content entry

<mark style="color:green;">`POST`</mark> `https://api.echo3D.com/upload`

This endpoint allows you to upload or edit assets.

#### Headers

| Name         | Type   | Description                                              |
| ------------ | ------ | -------------------------------------------------------- |
| Content-Type | string | Use `multipart/form-data` when uploading multiple files. |

#### Request Body

<table><thead><tr><th width="174">Name</th><th width="162">Type</th><th>Description</th></tr></thead><tbody><tr><td>key<mark style="color:red;">*</mark></td><td>string</td><td>Target collection key eg <code>some-words-1234</code></td></tr><tr><td>email<mark style="color:red;">*</mark></td><td>string</td><td>Your email address</td></tr><tr><td>userKey<mark style="color:red;">*</mark></td><td>string</td><td>Your authentication key</td></tr><tr><td>file<mark style="color:red;">*</mark></td><td>binary</td><td>The asset file associated with your request. Not required if using <code>url</code></td></tr><tr><td>url<mark style="color:red;">*</mark></td><td>string</td><td>The source url for the asset or AR target file. Not required if using <code>file</code></td></tr><tr><td>target_type</td><td>integer</td><td>AR target type, defaults to <code>2</code> (BRICK / no target) if not specified. Options: <code>0</code> for <code>IMAGE_TARGET</code>, <code>1</code> for <code>GEOLOCATION_TARGET</code>, or <code>2</code> for <code>BRICK_TARGET</code><strong>.</strong> See additional info about AR targets below. </td></tr><tr><td>data</td><td>string</td><td>A string representing metadata to add to the uploaded content. Format: <code>key1:value1;key2:value2;...</code></td></tr><tr><td>secKey</td><td>string</td><td>Collection Security Key. Only if enabled through the <a href="/pages/-M41x3tGykQ1P8zc6MV_#secret-key">Security page</a>.</td></tr><tr><td>allowDuplicate</td><td>boolean</td><td>Set to <code>true</code> to allow duplicate uploads. Duplicates are detected via an md5 checksum of the uploaded file</td></tr><tr><td>noProcessingWait</td><td>boolean</td><td>By default, Server waits up to 5 minutes for asset processing to complete before responding with complete asset object data. Include <code>noProcessingWait=true</code> in your request to prompt server to respond with basic asset data when asset is first saved to your collection. Processing times vary according to file size, platform load and asset format. Includes conversions to web-friendly formats and 3D model screenshots.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Content successfully uploaded." %}

```
{
  "id": "3b020b06-9ba1-42f1-87e7-eec3b33617c0",
  "target": {
    "id": "147fdbe5-2724-44ed-b6ec-31ae8bbbe50a",
    "type": "BRICK_TARGET",
    "holograms": [
      "bca5895d-29c6-4e74-b843-a014bdb0962c"
    ]
  },
  "hologram": {
    "filename": "Skyscraper.obj",
    "storageID": "d686a655-e800-430d-bfd2-e38cdfb0c9e9",
    "textureFilenames": [
      "Skyscraper_BaseColor.png"
    ],
    "textureStorageIDs": [
      "f9b43711-cf79-44e5-90c5-ac781c8d9288"
    ],
    "materialFilename": "Skyscraper.mtl",
    "materialStorageID": "891d0b32-4f4b-4f7d-a2e2-d5922611928d",
    "id": "bca5895d-29c6-4e74-b843-a014bdb0962c",
    "type": "MODEL_HOLOGRAM",
    "targetID": "147fdbe5-2724-44ed-b6ec-31ae8bbbe50a"
  },
  "sdks": [
    true,
    true,
    false,
    true,
    false,
    false,
    false,
    true,
    true
  ],
  "additionalData": {
    "accessHistory": "[\"1586222284478\"]",
    "createdAt": "1586222284478",
    "glbHologramStorageFilename": "Skyscraper.glb",
    "glbHologramStorageID": "d686a655-e800-430d-bfd2-e38cdfb0c9e9.glb",
    "lastAccessed": "1586222284478",
    "qrARjsMarkerStorageFilename": "marker_qr_arjs_blue-water-4646.png",
    "qrARjsMarkerStorageID": "5d8dc812-12ba-43a6-b00d-6f199bde16ce",
    "qrARjsStorageFilename": "qr_arjs_blue-water-4646.png",
    "qrARjsStorageID": "f32c0d9f-15b9-45b6-9371-630384ad588f",
    "qrARjsTargetStorageFilename": "qr_arjs_blue-water-4646.patt",
    "qrARjsTargetStorageID": "18e93bb9-a535-4764-94a4-6d6e5a16e260",
    "qrWebXRStorageFilename": "qr_webxr_blue-water-4646.png",
    "qrWebXRStorageID": "fbd798e7-fc13-43cd-bc9d-cfa0df1aabb6",
    "source": "Skyscraper by Poly by Google, CC-BY, https://poly.google.com/view/dIsZyy2FUY-",
    "vuforiaHologramStorageFilename": "Skyscraper.h",
    "vuforiaHologramStorageID": "7068cd74-6c9f-4106-9326-585c56fa4475"
  }
}
```

{% endtab %}

{% tab title="400 Could not find an API key in this query." %}

```
Key '<API_KEY>' not found!
```

{% endtab %}

{% tab title="200 Processing Timeout" %}
{% code fullWidth="true" %}

```
Processing did not complete in expected time. Your file was queued sucessfully and added to your collection. Please check back later or contact support if the issue persists.
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Target Type

&#x20;Target types can be one of the following:

### `0` for `IMAGE_TARGET`&#xD;

If you choose to use an image as your AR target, **you must also add** to your request **one** of the following:

* `url_image`: A URL to the image you want to use as a target
* `file_image`: The image file you want to use as a target. The file will be uploaded as Part.

### `1` for `GEOLOCATION_TARGET`&#xD;

A location target must be associated with a location. You must either send an address **or** send location coordinates (longitude and latitude):

* `text_geolocation`: Address for the location.
* `longitude` and `latitude`: Longitude and latitude coordinates

### `2` for `BRICK_TARGET`&#xD;

A surface target; needs no additional arguments.

## Examples

Here are a few upload API examples using [Postman](https://www.postman.com/).

1. Uploading an asset from a url

![](/files/KbPqQX8VFnyL7Xkaxl3i)

2. Uploading an asset from a local file on your PC

<figure><img src="/files/ERh6npbQlfjca4eXGpPw" alt=""><figcaption></figcaption></figure>

3. Uploading a model asset on a brick target from a third-party search engine:

* `type` is `search`, `source` is `Sketchfab`, and `url` includes an URL redirecting to the model
* `hologram_type` is `2`
* `target_type` is `2`

![](/files/-MXridEXTDqzgH9RJ8qG)

## Uploading with Metadata

You can attach a **.csv** file that contains pairs of keys and values to the Upload API call to be added alongside the uploaded asset as data entries. Your request **must include**:

* `file_csv` that includes a file

Your metadata file should contain only two columns: one for **keys** and the second for **values**.

<figure><img src="/files/-M9tGmk4Iq5L5lD0G009" alt=""><figcaption></figcaption></figure>

Here is a sample file you can use:

{% file src="/files/-M9tGw0oesRNMKmCPf0\_" %}

## Overwrite or Edit an Existing Entry

You can overwrite or edit an existing entry that was previously uploaded by using the upload API with a few additional parameters. Your request **must include**:

* `edit_type` that included the type of edit to make: `hologram` or `target.`
* `entryId` that included the Entry ID of the existing Entry to overwrite.

## Batch Upload

If you would like to upload many assets at once, the following repository allows for customized batch uploads via a Python script and a CSV data file. Click [here](https://github.com/echo3Dco/echo3D-Batch-Upload-script) to access the repository on GitHub.

{% embed url="<https://github.com/echo3Dco/Echo3D_upload_script>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.echo3d.com/api/upload.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.