> ## 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.

# Upload an image from a URL

> Store an image that is already published on the web. NeetoForm fetches it from the `url` and returns a `signed_id`. Pass the `signed_id` as `background_image` when you [create](/api/themes/create) or [update](/api/themes/update) a theme.

The address must use `https`, be reachable without credentials, and point to a public host. At most 2 redirects are followed. The image must be a PNG, JPEG, GIF or SVG of 1 MB or smaller. A `signed_id` works only in the workspace that created it.

To upload a file from your machine, use [Reserve an image upload](/api/images/reserve-upload). 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 /images
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:
  /images:
    post:
      tags:
        - Images
      summary: Upload an image from a URL
      description: >
        Store an image that is already published on the web. NeetoForm fetches
        it from the `url` and returns a `signed_id`. Pass the `signed_id` as
        `background_image` when you [create](/api/themes/create) or
        [update](/api/themes/update) a theme.


        The address must use `https`, be reachable without credentials, and
        point to a public host. At most 2 redirects are followed. The image must
        be a PNG, JPEG, GIF or SVG of 1 MB or smaller. A `signed_id` works only
        in the workspace that created it.


        To upload a file from your machine, use [Reserve an image
        upload](/api/images/reserve-upload). 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:
                url:
                  type: string
                  description: '`https` address of the image.'
                  example: https://example.com/files/banner.png
                filename:
                  type: string
                  description: >-
                    Name the image carries in the workspace. Taken from the
                    address when omitted.
                  example: hero.png
              required:
                - url
      responses:
        '201':
          description: Created - Image stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/image_response'
              example:
                signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0--abc123
                filename: hero.png
                content_type: image/png
                byte_size: 153
        '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 - The address is not valid or cannot be
            fetched, or the image is too large or not a supported type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
              examples:
                not_https:
                  summary: The address is not https
                  value:
                    error: >-
                      url must be an https address of the image, such as
                      'https://example.com/banner.png'.
                unreachable:
                  summary: The address cannot be fetched
                  value:
                    error: >-
                      The image at https://example.com/files/banner.png could
                      not be fetched. It must be publicly reachable over https
                      without credentials.
                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 text/html. 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_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
    error_response:
      type: object
      properties:
        error:
          type: string

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.