Customisers

get_upload

read

Get upload

Copy page

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

Overview

Read the status of an upload created through the current connection. Token refresh preserves access, and new consent requires a new upload. The response shows arrival, attachment, rejection, and expiry information. It never returns the presigned target. Requires customisers:read. Has no side effects.

Permission

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

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

Use an upload id created through the current connection, including after token refresh.
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

Call create_upload through the current connection with a fresh idempotency_key. PUT the bytes again. Use the new upload id.

Poll an upload that has arrived

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
      "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_00000000000000000000000000"
    }
  }
}

{
  "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": "Call create_upload through the current connection with a fresh idempotency_key. PUT the bytes again. Use the new upload id."
      }
    }
  }
}