# About the Ricos Documents API

The Ricos Documents API provides methods for working with Ricos documents, Wix's standardized format for rich content. Learn more about [Rich Content](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::df6eb24a-ca88-4058-a31b-ddc66ad2566f*fallback::https://dev.wix.com/docs/rest/articles/get-started/about-rich-content) and [Ricos documents](fallback::https://dev.wix.com/docs/ricos/getting-started/introduction).

With the Ricos Documents API, you can:
- Validate Ricos documents.
- Convert content from HTML, Markdown, or plain text to Ricos document format.
- Convert Ricos documents to HTML, Markdown, or plain text.
- Generate URLs for uploading files to use in Ricos documents.
- Generate temporary download URLs for files in Ricos documents.
- Generate site media tokens to open Wix media tools, such as Image Studio, from a Ricos editor.

## Before you begin

It's important to note the following points before starting to code:

- The API is stateless. It doesn't store Ricos documents, so pass the full document in each call.
- When converting content to a Ricos document, the plugins you specify affect HTML conversion only. Markdown and plain text conversions ignore them.
- File nodes in a Ricos document reference files in the site's [Media Manager](fallback::https://dev.wix.com/docs/api-reference/assets/media/media-manager/files) by ID. Call [Generate File Download URL](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/generate-file-download-url) to let site visitors download files from file nodes, including private files. To add a file to a document, call [Generate File Upload URL](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/generate-file-upload-url), upload the file, and reference its ID in a file node.
- Only Wix users can generate site media tokens, so call [Generate Site Media Token](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/generate-site-media-token) from a dashboard or editor page, not from a live site.

## Use cases

- [Convert site visitor input between Ricos document and Markdown formats](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/sample-flows#convert-site-visitor-input-between-ricos-document-and-markdown-formats)
- [Let site visitors add files to a Ricos document](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/sample-flows#let-site-visitors-add-files-to-a-ricos-document)
- [Let site visitors download files from a Ricos document](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/sample-flows#let-site-visitors-download-files-from-a-ricos-document)

## Terminology

- **Ricos document:** An object that defines rich content.
- **Plugin:** Allows rich content viewers to display specific content types. Learn more about [plugins](fallback::https://dev.wix.com/docs/ricos/getting-started/introduction#plugins).
- **File node:** A node of type `FILE` in a Ricos document. Its `fileData.src.id` holds the ID of the file in the site's Media Manager.

@sdk_package_setup

# Ricos Documents API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Convert site visitor input between Ricos document and Markdown formats
In this scenario, your app or site allows site visitors to create and edit content. They can choose whether to create the content using a rich content viewer or in a Markdown editor. They can toggle between the two formats while editing the content.

### When the site visitor toggles from rich content to Markdown
1. Call [Validate Document](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/validate-document), specifying:
    - The site visitor's current Ricos document.
    - The plugins your rich content viewer supports.
    - `fixDocument` set to `true`.

1. Call [Convert from Ricos Document](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/convert-from-ricos-document), specifying:
    - The `validDocument` value from the previous step's response.
    - The target format `MARKDOWN`.

    Use the response to populate your Markdown editor.

### When the site visitor toggles from Markdown to rich content
Call [Convert to Ricos Document](fallback::https://dev.wix.com/docs/rest/assets/rich-content/ricos-documents/convert-to-ricos-document), specifying:
- The site visitor's current Markdown content.
- The plugins your rich content viewer supports.

Use the response to populate your rich content editor.

## Let site visitors download files from a Ricos document
Your app or site displays Ricos documents to site visitors. Some documents contain file nodes, such as PDFs or audio files, that site visitors can download. Private files can't be downloaded from their regular URL, so your app generates a temporary download URL when a site visitor asks for the file.

To let site visitors download a file from a Ricos document:

1. Find the file node in the Ricos document and read its `fileData.src.id`.
1. When the site visitor clicks the file's download button, call [Generate File Download URL](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/generate-file-download-url), specifying the file ID as `fileId`.
1. Redirect the site visitor's browser to `downloadUrls[0].url` from the response. The browser downloads the file as an attachment.

    The URL expires after 10 hours, so generate a new URL each time a site visitor downloads the file instead of storing it.

## Let site visitors add files to a Ricos document
Your app or site lets site visitors create rich content, such as comments or forum posts, and attach files like PDFs to it. The files are stored in the site's Media Manager and referenced from file nodes in the Ricos document.

To let a site visitor add a file to a Ricos document:

1. When the site visitor selects a file, call [Generate File Upload URL](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/ricos-documents/generate-file-upload-url), specifying the file's `mimeType` and `fileName`. To keep the file from being publicly accessible, specify `private` as `true`.
1. Send a `PUT` request to `uploadUrl` from the response, with the file content as the request body and a `Content-Type` header matching `mimeType`. If you didn't specify `fileName`, add the file name as the `filename` query parameter. The upload URL expires after 24 hours.
1. From the upload response, take `file.id` and add a file node to the Ricos document with `fileData.src.id` set to this ID. If the file is private, also set `fileData.src.private` to `true`. For example:

    ```json
    {
      "type": "FILE",
      "id": "f1",
      "fileData": {
        "src": { "id": "734b7e_c7d9c79d94c548df8253770a9c2fe24e.pdf", "private": true },
        "name": "report.pdf",
        "type": "pdf"
      }
    }
    ```

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso