Skip to content
YoPrintDevelopers

Set an uploaded file's location or mockup flag

Open .md

PUT/v1/api/store/{team_slug}/async_upload/{hash_id}

v1Operation ID v1_public_async_upload_update_put

Saves location and show_mockup on a file, as custom properties. Use PUT with a JSON body.

Only values that are not empty or false are saved: you can set show_mockup to true but not back to false, and you can't clear location.

Permission

Any member of the team.

Business rules

  • location is text; show_mockup is a boolean.

Path parameters

  • team_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • hash_idstringrequired

    The file's id, from the upload answer. A hash id; unique keys and document numbers are refused with 404.

    • Example b0l2VJxwa3ppc7

Request body

application/json, required.

Response

200Successful response.

  • dataobjectrequired

    A file attached to a record has extra fields for it: job_id (with job_service and the current approval fields), job_preset_id (a job preset's file, with job_service: the preset's service ids), order_id, po_id or customer_id.

    Child fields (19)
    • assetUrlstring

      Images that are unattached uploads or job mockups only: a signed link the mockup editor uses. It expires; don't store it.

    • collectionstring

      An upload is default, mockup or production_file. A file attached to a record can be in another collection of that record.

    • created_atstring (date-time)
    • custom_propertiesobject | array

      Saved properties such as location and show_mockup. An empty list [] when there are none.

    • dimensionsobject | null

      Pixel size of an image, read from its header; null for other files and for images uploaded before the size was recorded.

      Child fields (2)
    • file_namestring
    • idstring

      The upload id. Pass it as attachment[].id to attach the file.

    • is_imageboolean
    • mime_typestring
    • namestring

      The original file name without its extension.

    • positioninteger | null

      The file's place in its list.

    • previewobject | null

      Preview links small, medium and large (250, 800 and 1200 px). Images up to 10 MB are their own preview, so they have these at once; a larger image has them once preview_state is ready. Other files have null while they are unattached uploads; once attached, some records (such as jobs) give them links to a converted preview.

      Child fields (3)
    • previewUrlstring

      Same images only: a signed preview link for the mockup editor. It expires; don't store it.

    • preview_statestring

      ready: the preview links work. processing: an image over 10 MB whose stored preview a worker is still making (seconds); read the file again, or in the web app wait for media.preview_state_changed on the team channel. too_large: an image over 120 megapixels; it never gets a preview. failed: the worker gave up, or the converter could not read the original (missing, broken or unsupported); it is not retried. none: not an image.

      • One of: "ready", "processing", "too_large", "failed", "none"
    • show_in_pdfboolean | null
    • sizeinteger

      Bytes.

    • source_media_idstring | null

      The file this one was copied from, when it is a copy. Always null on job and job preset files.

    • urlstring

      A signed download link. It expires; don't store it.

    • view_urlstring

      A signed link to view the file. It expires; don't store it.

  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  • 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

    When
    No file of this team has this id.
    Fix
    Use the id the upload returned.

  • 422Validation failed, or the image was refused by the media rules: a mockup that is not an image a preview can be made of (mockup_type_not_allowed), or an image over a size limit (image_not_allowed), or a file that is a web page, a script or a program (validation_failed on media, or upload_not_allowed: "This type of file cannot be uploaded."); error.message is one sentence naming the limit.

    When
    A new media file is a web page, a script or a program, judged by its extension and by its detected type (for example .html, .js, .php, .py, .sh, .exe, .bat, .jar, .apk, .app, .dmg). error.fields.media says "This type of file cannot be uploaded." (validation_failed).
    Fix
    Put the file in a .zip, or send a different file type.
    When
    A value has the wrong type, or you used PATCH without a media file (validation_failed; error.fields names the field).
    Fix
    Use PUT with JSON.

Notes

  • It works on any file of your team, including files already attached to a job.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com