> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.neetoform.com/llms.txt > Use this file to discover all available pages before exploring further. # Reserve an image upload > Reserve storage for an image on your machine. The response has a `signed_id` and the `upload_url` to send the bytes to. Then send the image bytes with an HTTP `PUT` to `upload_url`, with every header in `upload_headers` unchanged. Pass the `signed_id` as `background_image` when you [create](/api/themes/create) or [update](/api/themes/update) a theme. The `signed_id` works only after the bytes are uploaded, and only in the workspace that created it. Using it before the upload returns a 422 error. The `upload_url` is a short-lived credential. Do not share or log it. The image must be a PNG, JPEG, GIF or SVG of 1 MB or smaller. `checksum` is the base64-encoded MD5 digest of the file, which is what the `Content-MD5` header expects. It is not the hex digest. To upload an image that is already on the web, use [Upload an image from a URL](/api/images/upload-from-url). See [Upload a theme background image](/api/themes/background-image) for the full flow. > [!NOTE] > > Replace `{your-subdomain}` with your workspace’s subdomain. \ > Learn how to find your subdomain in [Workspace subdomain](https://apidocs.neetoform.com/api/workspace-subdomain.md). ## OpenAPI ````yaml bundled/images.yaml POST /image_uploads openapi: 3.0.3 info: title: NeetoForm Images APIs version: 2.0.0 servers: - description: NeetoForm APIs url: https://{your-subdomain}.neetoform.com/api/external/v2 variables: your-subdomain: default: spinkart description: >- Replace **spinkart** with your [workspace's subdomain](/api/workspace-subdomain). security: [] tags: - name: Images description: APIs to store images, such as a theme background image. paths: /image_uploads: post: tags: - Images summary: Reserve an image upload description: > Reserve storage for an image on your machine. The response has a `signed_id` and the `upload_url` to send the bytes to. Then send the image bytes with an HTTP `PUT` to `upload_url`, with every header in `upload_headers` unchanged. Pass the `signed_id` as `background_image` when you [create](/api/themes/create) or [update](/api/themes/update) a theme. The `signed_id` works only after the bytes are uploaded, and only in the workspace that created it. Using it before the upload returns a 422 error. The `upload_url` is a short-lived credential. Do not share or log it. The image must be a PNG, JPEG, GIF or SVG of 1 MB or smaller. `checksum` is the base64-encoded MD5 digest of the file, which is what the `Content-MD5` header expects. It is not the hex digest. To upload an image that is already on the web, use [Upload an image from a URL](/api/images/upload-from-url). See [Upload a theme background image](/api/themes/background-image) for the full flow. parameters: - $ref: '#/components/parameters/api_key_header' requestBody: required: true content: application/json: schema: type: object properties: filename: type: string description: Name the image carries, such as `banner.png`. example: banner.png byte_size: type: integer description: Size of the image in bytes. example: 153 checksum: type: string description: Base64-encoded MD5 digest of the image. Not the hex digest. example: 1B2M2Y8AsgTpgAmY7PhCfg== content_type: type: string description: >- Media type of the image. Inferred from the filename when omitted. enum: - image/png - image/jpeg - image/gif - image/svg+xml example: image/png required: - filename - byte_size - checksum responses: '201': description: Created - Upload reserved. Send the bytes to `upload_url` next. content: application/json: schema: $ref: '#/components/schemas/image_upload_response' example: signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0--abc123 filename: banner.png content_type: image/png byte_size: 153 checksum: 1B2M2Y8AsgTpgAmY7PhCfg== upload_url: >- https://acme.neetoform.com/rails/active_storage/disk/eyJfcmFpbHMi--abc123/banner.png upload_headers: Content-Type: image/png '401': description: Unauthorized - The API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/error_response' '403': description: Forbidden - The caller cannot manage themes content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: >- Unprocessable Entity - A field is missing or invalid, or the image is too large or not a supported type content: application/json: schema: $ref: '#/components/schemas/error_response' examples: filename_required: summary: filename is missing value: error: filename is required, such as 'banner.png'. checksum_required: summary: checksum is missing value: error: >- checksum is required. Pass the base64-encoded MD5 digest of the file, not the hex digest. invalid_byte_size: summary: byte_size is not a positive whole number value: error: >- byte_size must be the size of the file in bytes, a whole number above zero. too_large: summary: The image is larger than 1 MB value: error: The image must be 1 MB or smaller. unsupported_type: summary: The file is not a supported image value: error: >- The file is application/pdf. The image must be a PNG, JPEG, GIF or SVG image. components: parameters: api_key_header: in: header name: X-Api-Key description: >- Use the X-Api-Key header to provide your workspace API key. Refer to [Authentication](/api/authentication) for more information. required: true schema: type: string default: your-api-key schemas: image_upload_response: allOf: - $ref: '#/components/schemas/image_response' - type: object properties: checksum: type: string description: Base64-encoded MD5 digest the upload was reserved with. example: 1B2M2Y8AsgTpgAmY7PhCfg== upload_url: type: string description: >- Short-lived URL to send the image bytes to with an HTTP PUT. Treat it as a credential and do not share or log it. example: >- https://acme.neetoform.com/rails/active_storage/disk/eyJfcmFpbHMi--abc123/banner.png upload_headers: type: object additionalProperties: type: string description: Headers the PUT request must carry, exactly as given. example: Content-Type: image/png error_response: type: object properties: error: type: string image_response: type: object properties: signed_id: type: string description: >- Identifier of the stored image. Pass it as `background_image` when you create or update a theme. example: eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0--abc123 filename: type: string example: banner.png content_type: type: string example: image/png byte_size: type: integer description: Size of the image in bytes. example: 153 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.