# About the Ricos Site Context API

The Ricos Site Context API provides site-level context for rich content editors: the pages of the current Wix site that content can link to, and the site's base URL.

With the Ricos Site Context API, you can:

+ Retrieve the base URL of the site and whether the site is published.
+ List the static pages of the site.
+ List the dynamic pages of the site, and whether each one is the template of item pages.
+ List the item pages of a dynamic page.

## Before you begin

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

+ Static pages are sorted by title and returned with cursor paging. Dynamic pages are returned in one response, without paging. Item pages are returned with cursor paging. The default page size is 50, and the maximum is 100.
+ Static pages include the home page, pages that no Wix app manages, and the main pages of some Wix apps, such as the blog or the cart page. Other pages of Wix apps aren't included.
+ Static pages aren't filtered by whether they are hidden, password-protected or restricted to site members.
+ Dynamic pages include pages of Wix Data collections, and dynamic pages that no Wix app manages.
+ To list the item pages of a dynamic page, specify its `path` as `prefix`, and its `id` as `pageId`.
+ The `id` of an item page is an opaque key, not a page ID or a collection item ID. Don't specify it as `pageId`.
+ Store the `path` of a page as the link target, not its `url`. The `url` depends on the site's domain, which can change.
+ Item pages are read from the published version of the site. Check the `published` field of the response. If it's `false`, item pages aren't available yet.

## Use cases

Typical scenarios for using the Ricos Site Context API include:

+ [Let users link to a static page](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/sample-flows#let-users-link-to-a-static-page).
+ [Let users link to a dynamic item page](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/sample-flows#let-users-link-to-a-dynamic-item-page).

## Terminology

+ **Static page** - A page with a fixed path in the site.
+ **Dynamic page** - A page template that generates one page for each item in a collection.
+ **Item page** - One of the pages that a dynamic page generates, for a single item of a collection.
+ **Base URL** - The URL of the site, without a trailing slash. Every page `path` starts with `/`, so a page URL is the base URL followed by the `path`. Each page's `url` field already holds the full URL.

@sdk_package_setup

# Ricos Site Context 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.

## Let users link to a static page

A rich content editor can let users add a link to one of the site's pages, such as the home page or an about page. Store the page's `path` as the link target, so the link keeps working if the site's domain changes.

To let users link to a static page:

1. Call [List Static Pages](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-static-pages) to retrieve the pages. While `pagingMetadata.hasNext` is `true`, call it again with `paging.cursor` set to `pagingMetadata.cursors.next`.
2. Show the `title` of each page. When the user picks one, store its `path` as the link target.
3. To show a preview of the link, use the `url` of the page.
4. If `published` is `false`, tell users that the links don't work for visitors until the site is published.

## Let users link to a dynamic item page

A site with a collection, such as a list of team members in a Wix Data collection, has a dynamic page that generates one item page for each item. Users can link to a single item page.

To let users link to an item page:

1. Call [List Dynamic Pages](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-pages) to retrieve the dynamic pages.
2. Show the dynamic pages whose `hasItemPages` is `true`. If `published` is `false`, item pages aren't available yet, so don't show them.
3. When the user picks a dynamic page, call [List Dynamic Item Pages](fallback::https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-item-pages) with its `path` as `prefix` and its `id` as `pageId`. While `pagingMetadata.hasNext` is `true`, call it again with `paging.cursor` set to `pagingMetadata.cursors.next`.
4. Show the `title` of each item page. When the user picks one, store its `path` as the link target.

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

Frontend Modules

Wix Design System (WDS)

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

value

BoolValue

Int32Value

StringValue

GetSiteUrlRequest

Base URL of the site. It doesn't end with a slash, and a free Wix site includes the site name as a sub-path. For example, `https://www.example.com` or `https://username.wixsite.com/mysite`.
For a site that isn't published, it's the free URL that the site gets when it's published.

To build a page URL, append the page's `path`, which always starts with `/`.

baseUrl

Whether the site is published. If `false`, the item pages of dynamic pages aren't available yet, and page URLs can't be reached by visitors yet.

published

GetSiteUrlResponse

Request to list the item pages of a dynamic page.

`id` of the dynamic page, as [List Dynamic Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-pages) returns it. It's not the `id` of an item page.
Specify `pageId` to list only the item pages of that dynamic page. If you omit it, the item pages of all dynamic pages with this `prefix` are returned.

pageId

Cursor paging options.

Default: `paging.limit` is `50`.

`path` of the dynamic page, as [List Dynamic Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-pages) returns it. For example, `/items`.

prefix

ListDynamicItemPagesRequest

items

Paging metadata. To retrieve the next page of results, specify `cursors.next` in `paging.cursor`.

Whether the site is published. If `false`, item pages aren't available yet, and page URLs can't be reached by visitors yet.

ListDynamicItemPagesResponse

Request to list the dynamic pages of the site.

ListDynamicPagesRequest

Paging metadata. All dynamic pages are returned in one response, so `hasNext` is always `false`.

Whether the site is published. If `false`, page URLs can't be reached by visitors yet.

ListDynamicPagesResponse

Request to list the static pages of the site.

ListStaticPagesRequest

ListStaticPagesResponse

A placeholder entity of the Ricos site context service.

RicosSiteContextPlaceholder

A site page is a page of the current Wix site that rich content can link to. It's a static page, a dynamic page that generates one page for each item of a collection, or one of the item pages of a dynamic page.

Whether the dynamic page is the template of the item pages, as opposed to the page that lists the items.
Returned only for dynamic pages. `false` is also returned for a dynamic page that has no item pages.
If the site isn't published, item pages aren't available yet.

hasItemPages

Page ID of a static page or a dynamic page.
For an item page, this is an opaque key that identifies the item page. It isn't a page ID or a collection item ID, so don't specify it as `pageId` in [List Dynamic Item Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-item-pages), and don't parse it.

Path of the page within the site. Store `path`, not `url`, as the link target, because it doesn't depend on the site's domain.

Always starts with `/`. For example:
+ Static page: includes the paths of the parent pages. For example, `/about/team`.
+ Dynamic page: the path shared by its item pages. For example, `/items`.
+ Item page: the dynamic page's path followed by the item's path. For example, `/items/first-item`.

path

Page title. For an item page, the name of the item. Empty if the item has no name.

title

Full URL of the page: the site's base URL followed by `path`. Use it to display or preview the link, but don't store it.

SitePage

Cursor-based pagination parameters for listing requests.

Cursor token for pagination. Use the cursor from the previous response to get the next page of results.

cursor

limit

CursorPaging

Pagination metadata returned with list responses.

Number of items returned in the current response.

count

Navigation cursors for moving between result pages.

Whether there are more pages to retrieve following the current page.

hasNext

CursorPagingMetadata

Cursor for retrieving the next page of results.

Cursors

Retrieves the base URL of the current site and whether the site is published.

Use the base URL to build page URLs for display: `baseUrl` followed by the page's `path`.

To list the pages of the site, call [List Static Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-static-pages), [List Dynamic Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-pages) and [List Dynamic Item Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-item-pages).

Retrieves the base URL of the site and whether it's published

Get site URL

GetSiteUrl

Read Site Context for Rich Content

Lists the static pages of the current site, sorted by title, with cursor paging.

Returns the home page, pages that no Wix app manages, and the main pages of some Wix apps, such as the blog or the cart page. Other pages of Wix apps aren't returned. Pages aren't filtered by whether they're hidden, password-protected or restricted to site members.

To retrieve the next page of results, specify `pagingMetadata.cursors.next` from the previous response in `paging.cursor`.

The paging cursor is invalid or expired. Start again without a cursor.

Retrieves the static pages of the site and paginates through the results

List static pages

ListStaticPages

Lists the dynamic pages of the current site. Only dynamic pages of Wix Data collections, and dynamic pages that no Wix app manages, are returned. All pages are returned in one response, without paging.

A dynamic page is a page template that generates one page for each item of a collection. Each page indicates whether it's the template of the item pages (`hasItemPages`). To list the item pages of a dynamic page, call [List Dynamic Item Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-item-pages).

List dynamic pages

ListDynamicPages

Lists the item pages of a dynamic page, with cursor paging.

Specify the `path` of a dynamic page that [List Dynamic Pages](https://dev.wix.com/docs/api-reference/assets/rich-content/site-context-v1/list-dynamic-pages) returns as `prefix`, and its `id` as `pageId`.

Item pages are read from the published version of the site. If the `published` field of the response is `false`, item pages aren't available yet.

If `prefix` or `pageId` doesn't match a dynamic page of the site, no item pages are returned.

Retrieves the item pages of a dynamic page

List dynamic item pages

ListDynamicItemPages

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

nanos

seconds

GoogleProtoDuration

latitude

longitude

Location

name

number

StreetAddress

ListDynamicItemPagesOptions

ListDynamicItemPagesRequestSignature

ListStaticPagesOptions

ListStaticPagesRequestSignature

import { ricosSiteContext } from "@wix/rich-content";

async function getSiteUrl() {
  const response = await ricosSiteContext.getSiteUrl();
}

/* Promise resolves to:
 * {
 *   "baseUrl": "https://username.wixsite.com/mysite",
 *   "published": true
 * }
 */


Retrieves the base URL of the site and whether it's published.

import { createClient } from '@wix/sdk';
import { ricosSiteContext } from '@wix/rich-content';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { ricosSiteContext },
  // Include the auth strategy and host as relevant
});


async function getSiteUrl() {
  const response = await myWixClient.ricosSiteContext.getSiteUrl();
};

Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

getSiteUrl (self-managed)

import { ricosSiteContext } from "@wix/rich-content";

async function listStaticPages() {
  const response = await ricosSiteContext.listStaticPages({
    paging: {
      limit: 2,
    },
  });
}

/* Promise resolves to:
 * {
 *   "items": [
 *     {
 *       "_id": "c1dmp",
 *       "title": "About",
 *       "path": "/about",
 *       "url": "https://username.wixsite.com/mysite/about"
 *     },
 *     {
 *       "_id": "tuckg",
 *       "title": "Home",
 *       "path": "/home",
 *       "url": "https://username.wixsite.com/mysite/home"
 *     }
 *   ],
 *   "published": true,
 *   "pagingMetadata": {
 *     "count": 2,
 *     "cursors": {
 *       "next": "<NEXT_CURSOR>"
 *     },
 *     "hasNext": true
 *   }
 * }
 */


Retrieves the first 2 static pages of the site.

import { createClient } from '@wix/sdk';
import { ricosSiteContext } from '@wix/rich-content';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { ricosSiteContext },
  // Include the auth strategy and host as relevant
});


async function listStaticPages(options) {
  const response = await myWixClient.ricosSiteContext.listStaticPages(options);
};

listStaticPages (self-managed)

import { ricosSiteContext } from "@wix/rich-content";

async function listDynamicPages() {
  const response = await ricosSiteContext.listDynamicPages();
}

/* Promise resolves to:
 * {
 *   "items": [
 *     {
 *       "_id": "y80wh",
 *       "title": "Items (List)",
 *       "path": "/items",
 *       "url": "https://username.wixsite.com/mysite/items",
 *       "hasItemPages": false
 *     },
 *     {
 *       "_id": "es8i1",
 *       "title": "Items (Item)",
 *       "path": "/items",
 *       "url": "https://username.wixsite.com/mysite/items",
 *       "hasItemPages": true
 *     }
 *   ],
 *   "published": true,
 *   "pagingMetadata": {
 *     "count": 2,
 *     "hasNext": false
 *   }
 * }
 */


import { createClient } from '@wix/sdk';
import { ricosSiteContext } from '@wix/rich-content';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { ricosSiteContext },
  // Include the auth strategy and host as relevant
});


async function listDynamicPages() {
  const response = await myWixClient.ricosSiteContext.listDynamicPages();
};

listDynamicPages (self-managed)

import { ricosSiteContext } from "@wix/rich-content";

async function listDynamicItemPages() {
  const response = await ricosSiteContext.listDynamicItemPages("/items", {
    pageId: "es8i1",
    paging: {
      limit: 50,
    },
  });
}

/* Promise resolves to:
 * {
 *   "items": [
 *     {
 *       "_id": "items/{title}_602471ba-1d5e-4177-acd3-d63655d8fdb9",
 *       "title": "First item",
 *       "path": "/items/first-item",
 *       "url": "https://username.wixsite.com/mysite/items/first-item"
 *     }
 *   ],
 *   "published": true,
 *   "pagingMetadata": {
 *     "count": 1,
 *     "hasNext": false
 *   }
 * }
 */


Retrieves the item pages of a dynamic page.

import { createClient } from '@wix/sdk';
import { ricosSiteContext } from '@wix/rich-content';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { ricosSiteContext },
  // Include the auth strategy and host as relevant
});


async function listDynamicItemPages(prefix,options) {
  const response = await myWixClient.ricosSiteContext.listDynamicItemPages(prefix,options);
};