Assets endpoints

Uploads happen in two steps so file bytes never pass through the API: request an upload to get a presigned URL, PUT the bytes directly to storage, then finalize. A finalized asset can be placed in any design of the workspace by adding it with an asset operation and referencing its id from an image, SVG or video node.

Shell

# 1. request
UPLOAD=$(curl -sS -X POST "https://api.desyn.app/api/v1/assets/uploads" \
  -H "Authorization: Bearer $DESYN_API_KEY" -H "Content-Type: application/json" \
  -d "{\"name\":\"hero.jpg\",\"mime\":\"image/jpeg\",\"bytes\":$(stat -c %s hero.jpg)}")

# 2. upload the bytes with the returned URL and headers
curl -sS -X PUT "$(echo "$UPLOAD" | jq -r .uploadUrl)" -H "content-type: image/jpeg" --data-binary @hero.jpg

# 3. finalize
curl -sS -X POST "https://api.desyn.app/api/v1/assets/$(echo "$UPLOAD" | jq -r .assetId)/finalize" \
  -H "Authorization: Bearer $DESYN_API_KEY"

Allowed types and the maximum size per file depend on the plan (15 MB on Free, 200 MB on Pro, 1 GB self-hosted).

Assets#

Upload files in two steps (presigned PUT, then finalize) and manage the asset library.

Request an upload#

POST/assets/uploads

Convex assets.requestUploadScope assets:write

Validates type and size against your plan and returns a presigned PUT URL. Upload the bytes with exactly the returned headers, then finalize.

Parameters

namestringBodyRequired

File name.

mimestringBodyRequired

MIME type, e.g. image/png, image/svg+xml, font/woff2, video/mp4.

bytesintegerBodyRequired

Exact size in bytes.

sha256stringBody

Hex digest; identical files are deduplicated.

Shell

curl -X POST "https://api.desyn.app/api/v1/assets/uploads" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "hero.jpg",
  "mime": "image/jpeg",
  "bytes": 2483112
}'

201 Created

{
  "assetId": "a9b8c7d6e5f4",
  "uploadUrl": "https://s3.eu-north-1.amazonaws.com/desyn/uploads/a9b8c7d6e5f4?X-Amz-Signature=…",
  "headers": {
    "content-type": "image/jpeg"
  },
  "expiresAt": 1792484100000
}

Finalize an upload#

POST/assets/{assetId}/finalize

Convex assets.finalizeScope assets:write

Verifies the uploaded object, reads dimensions/duration, sanitizes SVG and marks the asset ready. Returns an AssetRef you can reference from nodes (add it to the design with an asset op).

Parameters

assetIdstringPathRequired

From the upload request.

Shell

curl -X POST "https://api.desyn.app/api/v1/assets/$ASSET_ID/finalize" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "id": "a9b8c7d6e5f4",
  "kind": "image",
  "mime": "image/jpeg",
  "bytes": 2483112,
  "width": 3000,
  "height": 2000,
  "source": "upload",
  "name": "hero.jpg",
  "status": "ready"
}

List assets#

GET/assets

Convex assets.listScope assets:read

Your uploads and generated assets, newest first.

Parameters

kind"image" | "svg" | "font" | "video" | "audio"Query

Filter by kind.

source"upload" | "ai" | "stock" | "brand"Query

Filter by origin.

limitintegerQuery

1–100, default 50.

cursorstringQuery

Pagination cursor.

Shell

curl "https://api.desyn.app/api/v1/assets" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "items": [
    {
      "id": "a9b8c7d6e5f4",
      "kind": "image",
      "name": "hero.jpg",
      "width": 3000,
      "height": 2000,
      "source": "upload"
    }
  ],
  "nextCursor": null
}

Get an asset#

GET/assets/{assetId}

Convex assets.getUrlScope assets:read

The asset's metadata and a signed GET URL (cached and reused until shortly before it expires).

Parameters

assetIdstringPathRequired

Asset id.

Shell

curl "https://api.desyn.app/api/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "id": "a9b8c7d6e5f4",
  "kind": "image",
  "mime": "image/jpeg",
  "url": "https://files.desyn.app/uploads/a9b8c7d6e5f4?sig=…",
  "expiresAt": 1792486800000
}

Rename an asset#

PATCH/assets/{assetId}

Convex assets.renameScope assets:write

Change the display name in the library.

Parameters

assetIdstringPathRequired

Asset id.

namestringBodyRequired

New name.

Shell

curl -X PATCH "https://api.desyn.app/api/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Hero — spring"
}'

200 OK

{
  "id": "a9b8c7d6e5f4",
  "name": "Hero — spring"
}

Delete an asset#

DELETE/assets/{assetId}

Convex assets.deleteScope assets:write

Removes it from the library. Designs that still use it keep a reference until they stop using it.

Parameters

assetIdstringPathRequired

Asset id.

Shell

curl -X DELETE "https://api.desyn.app/api/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "deleted": true
}