dotCMS

dotCMS File Assets API

File asset management and download operations

Documentation GitHub OpenAPI

Operations 5

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v1/content/fileassets/{inode}/resourcelink Get the resource link for a file asset · Find resource link 1 #

Ask an LLM

“What is the public link to a file asset I uploaded?”

“Can I get a file asset's resource URL from its inode?”

Tell an agent

Get the resource link for file asset {inode}.

Show the URL where file {inode} is served.

GET /api/v2/assets/{identifier} Download a file asset by identifier · Get raw file-asset content by identifier #

Ask an LLM

“How do I download the raw bytes of a file asset using its identifier?”

“Can I fetch the live published copy of a file instead of the working one?”

Tell an agent

Download file asset {identifier}.

Download the {version} version of file {identifier} in language {language}.

GET /api/v2/assets Download a file asset by site path · Get raw file-asset content by path #

Ask an LLM

“Can I download a file by its host and folder path, like //mysite/images/logo.png?”

“What happens if the file path I request doesn't exist?”

Tell an agent

Download the file at {path}.

Get the live version of file {path}.

PUT /api/v2/assets/publish Upload and publish a file asset · Publish file asset (working + live) #

Ask an LLM

“How do I upload a file and make it live immediately?”

“Can I replace a published image and push it live in one step?”

Tell an agent

Upload this file to the given host path and publish it live.

Replace the published file at that path with this upload and make it live.

PUT /api/v2/assets/save Upload a file asset as a draft · Save file asset (working version) #

Ask an LLM

“Can I upload a new version of a file without changing what's live?”

“How do I save a file asset as a working draft only?”

Tell an agent

Save this file to the host path as a working draft without publishing.

Upload a new working version of the file and leave the live one alone.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/dotcms:dotcms-file-assets-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: dotCMS REST File Assets API
  version: '3'
  description: File asset management and download operations
servers:
- url: /
  description: dotCMS Server
tags:
- name: File Assets
  description: File asset management and download operations
paths:
  /api/v1/content/fileassets/{inode}/resourcelink:
    get:
      tags:
      - File Assets
      operationId: findResourceLink_1
      parameters:
      - name: inode
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json;charset=UTF-8: {}
      summary: Find resource link 1
      x-summary-source: derived
  /api/v2/assets/{identifier}:
    get:
      tags:
      - File Assets
      summary: Get raw file-asset content by identifier
      description: Streams the raw bytes of a file asset addressed by its dotCMS identifier (UUID). Returns the working version in the site default language by default. READ permission is enforced — 403 is returned when the user lacks permission.
      operationId: getFileAssetById
      parameters:
      - name: identifier
        in: path
        description: Asset identifier (UUID)
        required: true
        schema:
          type: string
        example: 48190c8c-42c4-46af-8d1a-0cd5db894797
      - name: language
        in: query
        description: Language tag (e.g. en-US). Defaults to site default language.
        schema:
          type: string
        example: en-US
      - name: version
        in: query
        description: 'Asset version to retrieve. Accepted values: working (default), live.'
        schema:
          type: string
          enum:
          - working
          - live
          default: working
        example: working
      responses:
        '200':
          description: Raw file bytes streamed with resolved MIME type and Content-Disposition header
          content:
            application/octet-stream: {}
        '400':
          description: Bad Request — unknown language tag or version value
          content:
            application/json: {}
        '401':
          description: Unauthorized — authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden — user does not have READ permission on this asset
          content:
            application/json: {}
        '404':
          description: Not Found — identifier not found, not a file asset, or language version unavailable
          content:
            application/json: {}
  /api/v2/assets:
    get:
      tags:
      - File Assets
      summary: Get raw file-asset content by path
      description: Streams the raw bytes of a file asset addressed by a host-qualified path (//hostname/path/file.ext). Returns the working version by default; use version=live for the published version. Responds with 404 when the asset or language version does not exist, 400 when the path points at a folder.
      operationId: getFileAssetByPath
      parameters:
      - name: path
        in: query
        description: Host-qualified asset path, e.g. //demo.dotcms.com/application/foo.vtl
        required: true
        schema:
          type: string
        example: //demo.dotcms.com/application/containers/default/banner.vtl
      - name: language
        in: query
        description: Language tag (e.g. en-US). Defaults to site default language.
        schema:
          type: string
        example: en-US
      - name: version
        in: query
        description: 'Asset version to retrieve. Accepted values: working (default), live.'
        schema:
          type: string
          enum:
          - working
          - live
          default: working
        example: working
      responses:
        '200':
          description: Raw file bytes streamed with resolved MIME type and Content-Disposition header
          content:
            application/octet-stream: {}
        '400':
          description: Bad Request — path is missing, ambiguous, points at a folder, or unknown language/version value
          content:
            application/json: {}
        '401':
          description: Unauthorized — authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden — insufficient read permissions
          content:
            application/json: {}
        '404':
          description: Not Found — host, path, or language version does not exist
          content:
            application/json: {}
  /api/v2/assets/publish:
    put:
      tags:
      - File Assets
      summary: Publish file asset (working + live)
      description: 'Creates or updates a file asset at the given host-qualified path and immediately publishes it (promotes to live). Submit via multipart/form-data with fields: file (binary), path (//host/folder/file.ext), language (optional).'
      operationId: publishFileAsset
      requestBody:
        description: 'Multipart form with fields: file (binary content, required), path (host-qualified asset path including filename, required), language (language tag, optional — defaults to site default)'
        content:
          multipart/form-data:
            schema:
              type: object
              description: 'Flat multipart form: file, path, language'
        required: true
      responses:
        '200':
          description: Asset saved and published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityFileAssetView'
        '400':
          description: Bad Request — missing file part, zero-byte file, unknown language, or invalid path
          content:
            application/json: {}
        '401':
          description: Unauthorized — authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden — insufficient permissions on target folder
          content:
            application/json: {}
        '404':
          description: Not Found — unknown host in path
          content:
            application/json: {}
  /api/v2/assets/save:
    put:
      tags:
      - File Assets
      summary: Save file asset (working version)
      description: 'Creates or updates a file asset at the given host-qualified path. Only the working version is affected — the live version is NOT changed. Submit via multipart/form-data with fields: file (binary), path (//host/folder/file.ext), language (optional).'
      operationId: saveFileAsset
      requestBody:
        description: 'Multipart form with fields: file (binary content, required), path (host-qualified asset path including filename, required), language (language tag, optional — defaults to site default)'
        content:
          multipart/form-data:
            schema:
              type: object
              description: 'Flat multipart form: file, path, language'
        required: true
      responses:
        '200':
          description: Asset saved successfully as working version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEntityFileAssetView'
        '400':
          description: Bad Request — missing file part, zero-byte file, unknown language, or invalid path
          content:
            application/json: {}
        '401':
          description: Unauthorized — authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden — insufficient permissions on target folder
          content:
            application/json: {}
        '404':
          description: Not Found — unknown host in path
          content:
            application/json: {}
components:
  schemas:
    MessageEntity:
      type: object
      properties:
        message:
          type: string
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          format: int32
        perPage:
          type: integer
          format: int32
        totalEntries:
          type: integer
          format: int64
    ErrorEntity:
      type: object
      properties:
        errorCode:
          type: string
        message:
          type: string
        fieldName:
          type: string
    ResponseEntityFileAssetView:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEntity'
        entity:
          $ref: '#/components/schemas/FileAssetView'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageEntity'
        i18nMessagesMap:
          type: object
          additionalProperties:
            type: string
        permissions:
          type: array
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
      description: Response entity wrapping a FileAssetView after a save or publish operation
    FileAssetView:
      type: object
      properties:
        identifier:
          type: string
          description: Asset identifier
          example: 48190c8c-42c4-46af-8d1a-0cd5db894797
        inode:
          type: string
          description: Asset inode
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: File name
          example: banner.vtl
        path:
          type: string
          description: Host-qualified path to the asset
          example: //demo.dotcms.com/application/containers/default/banner.vtl
        lang:
          type: string
          description: Language tag for the asset version
          example: en-US
        live:
          type: boolean
          description: Whether this is the live (published) version
          example: false
        working:
          type: boolean
          description: Whether this is the working version
          example: true
        fileSize:
          type: integer
          description: File size in bytes as stored in the content repository
          format: int64
          example: 4096
      description: File asset view returned after a save or publish operation

dotCMS File Assets API

Operations 5

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification