> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create asset

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Adds a file that's already online to the app's media library, by its URL. Base44 doesn't download the file. To store a file with Base44, use [Upload asset](/api-reference/upload-asset) instead.

In this response, `created_date` and `updated_date` include a `+00:00` offset. [List assets](/api-reference/list-assets) returns them without one.

This endpoint is limited to 120 requests per minute, shared with Create asset, Rename asset and Delete asset. Some workspaces have a different limit.

<Note>This endpoint accepts a personal API key belonging to a user with editor access to the app, or a workspace API key, which acts as the workspace owner. A read-only key is refused.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/assets
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/assets:
    post:
      summary: Create asset
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Adds a file that's already online to the app's media library, by its
        URL. Base44 doesn't download the file. To store a file with Base44, use
        [Upload asset](/api-reference/upload-asset) instead.


        In this response, `created_date` and `updated_date` include a `+00:00`
        offset. [List assets](/api-reference/list-assets) returns them without
        one.


        This endpoint is limited to 120 requests per minute, shared with Create
        asset, Rename asset and Delete asset. Some workspaces have a different
        limit.


        <Note>This endpoint accepts a personal API key belonging to a user with
        editor access to the app, or a workspace API key, which acts as the
        workspace owner. A read-only key is refused.</Note>


        <Warning>The response includes fields beyond the ones documented here.
        Don't rely on undocumented response fields, as they can change at any
        time. Send only the fields documented here. Other request fields are not
        supported and their behavior can change.</Warning>
      operationId: create_asset_api_apps__app_id__assets_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app whose media library to change.
            title: App Id
          description: ID of the app whose media library to change.
          example: 6820f3a4e7b91d003c45a1f2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetRequest'
            example:
              file_name: Logo-dark.png
              file_url: https://cdn.acme.com/brand/Logo-dark.png
              file_type: png
      responses:
        '200':
          description: The new asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetSummary'
        '400':
          description: >-
            `file_url` isn't an `http` or `https` URL, or points to an address
            that isn't allowed.
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have editor access to this app, the app is blocked, or
            your API key is read-only.
        '404':
          description: App not found.
        '422':
          description: >-
            `file_name` or `file_url` is missing, or `source_type` isn't
            `upload` or `generated`.
        '429':
          description: >-
            Rate limit exceeded. The base limit is 120 requests per minute. See
            [Rate
            limits](/developers/references/apps-api/get-started/rate-limits) for
            the multiplier your plan gets.
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    CreateAssetRequest:
      properties:
        file_name:
          type: string
          title: File Name
          description: >-
            Name of the file. Characters other than letters, digits, `_`, `.`
            and `-` become `_`, anything up to the last `/` is dropped, and an
            empty name becomes `untitled`.
          example: Logo-dark.png
        file_url:
          type: string
          title: File Url
          description: >-
            Public `http` or `https` URL of the file. Base44 doesn't download or
            copy it, so the asset stays a link to this URL. Addresses on private
            networks and Base44's own hosts, other than its media CDN, are
            refused.
          example: >-
            https://media.base44.com/files/public/6820f3a4e7b91d003c45a1f2/Logo-dark.png
        source_type:
          type: string
          enum:
            - upload
            - generated
          title: Source Type
          description: >-
            How the file got into the library, `upload` or `generated`. Defaults
            to `upload`.
          default: upload
          example: upload
        file_type:
          anyOf:
            - type: string
            - type: 'null'
          title: File Type
          description: >-
            File extension without the dot, such as `png`. Stored as you send
            it, and used by the `file_type` filter in List assets. Leave it out
            to store `null`.
          example: png
      type: object
      required:
        - file_name
        - file_url
      title: CreateAssetRequest
    AssetSummary:
      properties:
        id:
          type: string
          title: Id
          description: ID of the asset.
          example: 68b0e1f2a3c4d5e6f7a8b9c0
        app_id:
          type: string
          title: App Id
          description: ID of the app the asset belongs to.
          example: 6820f3a4e7b91d003c45a1f2
        file_name:
          type: string
          title: File Name
          description: Name of the file.
          example: Logo-dark.png
        file_url:
          type: string
          title: File Url
          description: URL of the file.
          example: >-
            https://media.base44.com/files/public/6820f3a4e7b91d003c45a1f2/Logo-dark.png
        source_type:
          type: string
          enum:
            - upload
            - generated
          title: Source Type
          description: >-
            How the file got into the library. `upload` for a file someone
            uploaded, and `generated` for most files Base44 created for the app,
            such as AI-generated images and videos or a Figma import.
          example: upload
        file_type:
          anyOf:
            - type: string
            - type: 'null'
          title: File Type
          description: >-
            File extension without the dot, usually lowercase, such as `png` or
            `mp4`. The value is `null` when the file was added without one.
          example: png
        created_date:
          type: string
          title: Created Date
          description: >-
            When the asset was added to the library, as a UTC timestamp in ISO
            8601 format.
          example: '2026-01-15T09:23:41'
        updated_date:
          type: string
          title: Updated Date
          description: >-
            When the asset was last changed, such as renamed, as a UTC timestamp
            in ISO 8601 format.
          example: '2026-01-15T09:31:07'
      type: object
      required:
        - id
        - app_id
        - file_name
        - file_url
        - source_type
        - file_type
        - created_date
        - updated_date
      title: AssetSummary
      description: A file in the app's media library.
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

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