Customisers

get_upload

read

Get upload

Copy page

Check whether a staged upload is ready to attach, or why it was rejected.

Overview

Reads the state of one staged upload: whether the bytes have arrived, whether they passed verification, whether the object has been attached to a slot, and when the staging target expires. It is the call to poll between creating an upload and attaching it, and the place to look when an attach fails with an upload error. The presigned target is never returned here. It requires the customisers:read scope and has no side effects.

Permission

Requires thecustomisers:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

An upload id from create_upload.
A merchant has connected this store and approved the customisers:read scope.

Arguments

upload_idstringrequired

The upload id create_upload returned.

Result

One upload record. The presigned target and its headers are deliberately omitted; they are returned only once, by create_upload.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

upload_idstringalways present

statusstringalways present

Where the upload is in its lifecycle. Expected to grow: tolerate unknown values.

One of: pending, uploaded, attached, rejected, expired

purposestringalways present

What the upload was declared for, which fixes its allowed content types and maximum size. Expected to grow.

One of: font_ttf, option_image, option_texture_image, backboard_shape_svg, label_image

filenamestring or null

content_typestring or null

byte_sizeinteger or null

verification_failure_codestring or null

Why verification rejected the object, or null when it has not been rejected.

expires_atstring or null

attached_atstring or null

created_atstring or null

Error cases

insufficient_scope

The connection was approved without customisers:read.

resource_not_found

No upload with that id belongs to this store, or it was pruned after expiring. Start again at create_upload.

Poll an upload that has arrived

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_upload",
    "arguments": {
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd",
      "status": "uploaded",
      "purpose": "font_ttf",
      "filename": "Signature.ttf",
      "content_type": "font/ttf",
      "byte_size": 184320,
      "verification_failure_code": null,
      "expires_at": "2026-07-23T00:00:00Z",
      "attached_at": null,
      "created_at": "2026-07-22T00:00:00Z"
    }
  }
}

An upload id that has already been pruned (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_upload",
    "arguments": {
      "upload_id": "upl_000000000000000000000"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_not_found",
        "title": "Resource not found",
        "detail": "The requested resource does not exist or does not belong to the authenticated store.",
        "recovery": "The identifier does not exist in this store. Use the matching list tool to rediscover a valid id."
      }
    }
  }
}