Assets

Upload Files

POST /v1/uploads uploads a file and creates an asset in one request.

Send:

• the file bytes as the raw request body
• Content-Type as the file MIME type
• x-file-name as the original filename
• optional x-project-id if the uploaded file should be attached to a project immediately

Reuse Uploaded Files In Editor JSON

The upload and asset APIs return two fields you should write into editor JSON:

• fileUrl -> assets[*].remoteUrl
• fileKey -> assets[*].remoteKey

Example:

{
  "assets": {
    "hero-image": {
      "type": "image",
      "remoteUrl": "https://cdn.example.com/uploads/hero.png",
      "remoteKey": "uploads/hero.png"
    }
  }
}

The editor JSON asset map key such as hero-image is not the same thing as the OpenAPI assetId.

Attach Assets To Projects

If you send x-project-id during upload, the created asset is attached to that project automatically.

You can also manage project bindings later:

• GET /v1/projects/{projectId}/assets
• POST /v1/projects/{projectId}/assets
• DELETE /v1/projects/{projectId}/assets/{assetId}

Get And Delete Assets

• GET /v1/assets/{assetId} returns reusable asset fields
• DELETE /v1/assets/{assetId} deletes the asset only when reference checks pass

If the asset is still referenced, the API returns ASSET_REFERENCED.