Assets

Asset endpoints manage the asset tree and upload or download asset files.

Uploading a file and creating an asset record are separate operations:

1. Upload the binary with /asset/upload.
2. Use the returned filename in POST /asset or PATCH /asset/{assetID}.

Endpoints

Get assets # GET/api/v1/{hash}/asset

Request

HTTP

GET /api/v1/{hash}/asset

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset"

Response

Returns 200 OK with a compact representation of the complete asset tree:

[
  {
    "id": "root_asset",
    "name": "Root",
    "type": "folder",
    "parentId": null,
    "children": ["image_1", "audio_folder"]
  },
  {
    "id": "image_1",
    "name": "Castle.png",
    "type": "image",
    "parentId": "root_asset",
    "children": []
  },
  {
    "id": "audio_folder",
    "name": "Audio",
    "type": "folder",
    "parentId": "root_asset",
    "children": []
  }
]

Every entry contains id, name, type, parentId, and children. Folder entries, including the internal root, use type: "folder". File assets use their stored asset type. File asset names include the stored file extension when one is available.

Get asset # GET/api/v1/{hash}/asset/{assetID}

Request

HTTP

GET /api/v1/{hash}/asset/{assetID}

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}"

Response

Returns 200 OK.

File-bearing assets include type and file:

{
  "id": "a01",
  "name": "asset 1",
  "type": "image",
  "file": "asset_1.jpg"
}

Folders include children and do not include file-bearing properties.

Upload file # POST/api/v1/{hash}/asset/upload

Request

HTTP

POST /api/v1/{hash}/asset/upload
Content-Type: multipart/form-data

curl

curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --form "type=image" \
  --form "file=@path/to/file.png" \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/upload"

Form fields:

Property	Required	Type	Description
file	Yes	File	Binary upload.
type	Yes	String	image, audio, or video.

Supported formats and limits

The uploaded file must match the selected type:

type	Accepted formats
image	JPEG (.jpeg, .jpg), PNG, GIF, WebP
audio	MPEG/MP3, Ogg, WAV, WebM
video	MP4, WebM, Ogg

Arcweave checks the file's content to determine its MIME type. Renaming a file's extension does not make an unsupported format valid.

• Images have separate width and height limits, each defaulting to 8192 pixels. These limits are configurable on the server; a validation error reports the applicable limit.
• The workspace plan sets the maximum size of one file and the total asset size per project. Standard Team limits are 400 MB per file and 10 GB per project; see asset upload limits.
• The total-size check includes the project's existing assets plus the incoming file. Uploading the binary does not create an asset record; complete the second step with Create asset or folder.

Unsupported file content, exceeded image dimensions, and exceeded plan limits return 400 Bad Request with details in errors.file. Request-size limits on the server can reject an oversized upload before API validation runs.

Response

Returns 200 OK with metadata for the stored file:

{
  "filename": "b7f4a0c1.png",
  "name": "castle",
  "size": "12.06 KB"
}

Create asset or folder # POST/api/v1/{hash}/asset

Request

HTTP

POST /api/v1/{hash}/asset

curl

curl --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset"

Create a file-bearing asset from an uploaded file:

{
  "name": "Castle",
  "type": "image",
  "file": "b7f4a0c1.png",
  "parentId": "folder_1",
  "index": 0
}

Create a folder by omitting type and file:

{
  "name": "Locations"
}

Property	Required	Type	Description
name	Yes	String	Asset or folder name.
type	No	String	image, audio, or video. Omit to create a folder.
file	No	String	Stored filename returned by the upload endpoint.
size	No	String	Display size, such as the size returned by the upload endpoint.
volume	No	Number	Initial volume metadata, normally used by audio assets.
parentId	No	String or null	Target folder. Defaults to the root asset container.
index	No	Non-negative integer or "-"	Position in the target folder. Defaults to "-", which appends the item.

When file, size, or volume is supplied, type is required. If the stored file exists, Arcweave calculates its actual size and uses that value. A file-bearing asset may be created without file and populated later with the update endpoint.

The target parent must exist and be a folder. Template asset trees are read-only.

Response

Returns 201 Created with the generated resource ID and project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"],
  "id": "65139ea3-331f-4b25-88b4-ea7a65ff106c"
}

Update asset # PATCH/api/v1/{hash}/asset/{assetID}

Request

HTTP

PATCH /api/v1/{hash}/asset/{assetID}

curl

curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}"

{
  "name": "Updated Castle",
  "file": "updated_file.png"
}

Request fields:

Property	Required	Type	Description
name	No	String	Updated name. If omitted, the current value is retained.
type	No	String	image, audio, or video. If omitted, the current value is retained.
file	No	String	Updated stored filename. If omitted, the current value is retained.
size	No	String	Updated display size. Arcweave uses the actual size for a stored file.
volume	No	Number	Updated volume metadata.

• Folders may be renamed but cannot receive file-asset properties.
• Template assets cannot be modified.
• The internal root_asset container cannot be modified.

Response

Returns 200 OK with project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}

Move or reorder asset # PATCH/api/v1/{hash}/asset/{assetID}/index

Request

HTTP

PATCH /api/v1/{hash}/asset/{assetID}/index

curl

curl --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}/index"

{
  "parentId": "folder_1",
  "index": 0
}

Request fields:

Property	Required	Type	Description
parentId	No	String or null	Target folder. Omit to keep the current parent; use null for the root.
index	Yes	Non-negative integer	New position within the target folder.

• index is required.
• Omit parentId to reorder within the current folder.
• Use "parentId": null to move to the root asset container.
• The target must be a folder.
• An asset folder cannot be moved into itself or one of its descendants.
• The root and template asset trees cannot be moved.

Response

Returns 200 OK with project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}

Delete asset # DELETE/api/v1/{hash}/asset/{assetID}

Request

HTTP

DELETE /api/v1/{hash}/asset/{assetID}

curl

curl --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}"

Deleting a folder deletes its subtree. The root and template asset trees cannot be deleted.

Response

Returns 200 OK with project version data:

{
  "version": 12,
  "newVersion": 13,
  "versionTime": ["1720788000", "123456"]
}

Download asset file # GET/api/v1/{hash}/asset/{assetID}/file

Request

HTTP

GET /api/v1/{hash}/asset/{assetID}/file

curl

curl --request GET \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json" \
  "https://arcweave.com/api/v1/PROJECT_HASH/asset/{assetID}/file"

Response

Returns 200 OK with the binary asset file. The Content-Type matches the stored asset type.

The response is the stored binary. Folders are not downloadable. Both project-uploaded and referenced template asset files can be returned.

Common errors

Status	Meaning
400	Invalid metadata/upload, folder file mutation, root/template mutation, non-folder parent, recursive move, or plan limit exceeded.
403	Project permission denied.
404	Project, asset, parent, or stored file not found.
409	Asset or parent changed before the command was applied.