useStatamicApi
Provides a comprehensive API interface for interacting with Statamic CMS.
Added since: v1.0.0
Last changed:
Usage
The useStatamicApi composable is used to provide a comprehensive API interface for interacting with Statamic CMS.
It offers methods to fetch entries, navigations, globals, forms, taxonomies etc.
The composable by default, handles the following:
- Preview mode tokens -
useStatamicPreviewMode - Site filtering -
useStatamicSite(multi-tenancy or multi-lingual) - Throws an error if the
$apiinstance is not available (e.g., used before plugin initialization).[nuxt-statamic]: '`useStatamicApi` is used before the `statamic:plugin` was able to provide the `$api` e.g. custom fetch instance'
Type Definition
function useStatamicApi() {
return {
entries: fetchEntries, // Fetch entries from a specified collection.
entry: fetchEntry, // Fetch a specific entry by its ID from a collection.
entryByUri: fetchEntryByUri, // Fetch an entry by its URI (URL path).
collection: fetchCollection, // Fetch a collection tree by its handle.
navigations: fetchNavigations, // Fetch all configured navigations asynchronously.
navigation: fetchNavigation, // Fetch a specific navigation by its handle.
globals: fetchGlobals, // Fetch all globals for the current site.
global: fetchGlobal, // Fetch a specific global by its handle.
forms: fetchForms, // Fetch all available forms.
form: fetchForm, // Fetch a specific form by its handle.
submitForm, // Submit form data to a specific form.
taxonomyTerms: fetchTaxonomyTerms, // Fetch terms from a specific taxonomy.
taxonomyTerm: fetchTaxonomyTerm, // Fetch a specific taxonomy term by its slug.
graphql: fetchGraphql, // Execute a GraphQL query against the Statamic API.
redirects: fetchRedirects, // Fetch all redirects for the current site.
sitemapUrls: fetchSitemapUrls, // Fetch the sitemap URLs.
};
};
API Reference
entries()
See the Statamic REST API documentation for entries for more information.
Fetches entries from a specified collection.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data: blogs } = await useAsyncData(
useStatamicCacheKey("entries", "blogs"),
() => api.entries("blogs")
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data: blogs } = await useAsyncData(
useStatamicCacheKey("entries", "blogs"),
() => api.entries("blogs", {
fields: ["title", "content", "slug", "author"],
order: "sort",
limit: 200,
}),
);
</script>
Type Definition
function fetchEntries<DataType extends Record<string, any> = StatamicApiEntryDefaultFields>(
collection: string,
params: Partial<StatamicApiParamsMultiple<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseMultiple<DataType>>;
Params
collection
string required
The handle of the collection to fetch entries from
params
Partial<StatamicApiParamsMultiple<DataType>>
Optional parameters for filtering, pagination, field selection and other options
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseMultiple<DataType>>
Promise that resolves to the collection entries
entry()
See the Statamic REST API documentation for a specific entry for more information.
Fetches a specific entry by its ID from a collection.
Usage
Basic example
<script setup lang="ts">
const linkedBlog = computed(() => page.value?.linked_blog);
const api = useStatamicApi();
const { data: blog } = await useAsyncData(
useStatamicCacheKey("entry", "blog", linkedBlog.value?.id),
() => api.entry("blogs", linkedBlog.value?.id),
);
</script>
Type Definition
function fetchEntry<DataType extends Record<string, any> = StatamicApiEntryDefaultFields>(
collection: string,
entryId: string,
params: Partial<StatamicApiParamsSingle<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseSingle<DataType>>;
Params
collection
string required
The handle of the collection to fetch entries from
entryId
string required
The ID of the entry to fetch
params
Partial<StatamicApiParamsSingle<DataType>>
Optional parameters for field selection and other options
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseSingle<DataType>>
Promise that resolves to the entry data
entryByUri()
Fetches an entry by its URI (URL path).
Usage
Basic example
<script setup lang="ts">
const route = useRoute();
const api = useStatamicApi();
const {data: styleguideData} = await useAsyncData(
useStatamicCacheKey('entry', 'page', route.path),
() => api.entryByUri({uri: route.path}),
);
</script>
Type Definition
function fetchEntryByUri<DataType extends Record<string, any> = StatamicApiEntryDefaultFields>(
params: Partial<StatamicApiParamsUri<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseSingle<DataType>>;
Params
params
Partial<StatamicApiParamsUri<DataType>> required
Parameters including the URI to fetch and optional field selection
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseSingle<DataType>>
Promise that resolves to the entry data
collection()
See the Statamic REST API documentation for a collection tree for more information.
Fetches a collection tree by its handle.
Usage
Basic example
<script setup lang="ts">
const api = useStatamicApi();
const {data: styleguideData} = await useAsyncData(
useStatamicCacheKey('collection', 'blogs'),
() => api.collection('blogs'),
);
</script>
Type Definition
function fetchCollection<DataType extends Record<string, any> = StatamicApiEntryDefaultFields>(
collectionHandle: string,
params: Partial<StatamicApiParamsTree<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseTree<DataType>>;
Params
collectionHandle
string required
The handle of the collection to fetch the tree from
params
Partial<StatamicApiParamsTree<DataType>>
Optional parameters for field selection and other options
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseTree<DataType>>
Promise that resolves to the collection tree data
navigations()
See the Statamic REST API documentation for navigation tree for more information.
This method is already called by the module. You can use this method to manually fetch the navigations if you need to.
Fetches all configured navigations asynchronously.
This method fetches all navigations defined in the Statamic runtime config and returns them as a keyed object where each key is the navigation handle.
This is by default a server side method and is therefore cached. When you need to fetch the navigations on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("navigations", "all"),
() => api.navigations()
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("navigations", "all"),
() => api.navigations({}, { baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
async function fetchNavigations<DataType extends Record<string, any>>(
params: Partial<StatamicApiParamsTree<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
);
Params
params
Partial<StatamicApiParamsTree<DataType>>
Optional parameters to apply to all navigation requests
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to an object with navigation handles as keys
navigation()
See the Statamic REST API documentation for navigation tree for more information.
Fetches a specific navigation by its handle.
This is by default a server side method and is therefore cached. When you need to fetch the navigation on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("navigation", "header"),
() => api.navigation("header")
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("navigation", "header"),
() => api.navigation("header", {}, { baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
function fetchNavigation<DataType extends Record<string, any>>(
navigationHandle: string,
params: Partial<StatamicApiParamsTree<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseTree<DataType>>;
Params
navigationHandle
string required
The handle of the navigation to fetch
params
Partial<StatamicApiParamsTree<DataType>>
Optional parameters for field selection and other options
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseTree<DataType>>
Promise that resolves to the navigation tree data
globals()
See the Statamic REST API documentation for globals for more information.
This method is already called by the module. You can use this method to manually fetch the globals if you need to.
Fetches all globals for the current site.
The response is automatically transformed to return an object where each key is the global handle, making it easier to access specific globals.
This is by default a server side method and is therefore cached. When you need to fetch the globals on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("globals", "all"),
() => api.globals()
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("globals", "all"),
() => api.globals({}, { baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
function fetchGlobals<DataType extends Record<string, any>>(
params: Partial<Pick<StatamicApiParamsTree<DataType>, "site">> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<Record<string, any>>;
Params
params
Partial<Pick<StatamicApiParamsTree<DataType>, 'site'>>
Optional parameters for filtering
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to an object with global handles as keys
global()
See the Statamic REST API documentation for a specific global for more information.
Fetches a specific global by its handle.
This is by default a server side method and is therefore cached. When you need to fetch the global on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("global", "site"),
() => api.global("site")
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("global", "site"),
() => api.global("site", {}, { baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
function fetchGlobal<DataType extends Record<string, any>>(
globalHandle: string,
params: Partial<Pick<StatamicApiParamsTree<DataType>, "site">> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseSingle<DataType>>;
Params
globalHandle
string required
The handle of the global to fetch
params
Partial<Pick<StatamicApiParamsTree<DataType>, 'site'>>
Optional parameters for filtering
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseSingle<DataType>>
Promise that resolves to the global data
forms()
See the Statamic REST API documentation for forms for more information.
Fetches all available forms.
Usage
Basic example
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("forms", "all"),
() => api.forms(),
);
</script>
Type Definition
function fetchForms(
fetchOptions: FetchOptions = {},
): Promise<Record<string, any>>;
Params
fetchOptions
FetchOptions = {}
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to the forms data
form()
See the Statamic REST API documentation for a specific form for more information.
Fetches a specific form by its handle.
Usage
Basic example
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("form", "contact"),
() => api.form("contact"),
);
</script>
Type Definition
function fetchForm(
formHandle: string,
fetchOptions: FetchOptions = {},
): Promise<Record<string, any>>;
Params
formHandle
string required
The handle of the form to fetch
fetchOptions
FetchOptions = {}
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to the form data
submitForm()
Submits form data to a specific form.
Type Definition
function submitForm(
formHandle: string,
data: Record<string, any>,
fetchOptions: FetchOptions = {},
): Promise<Record<string, any>>;
Params
formHandle
string required
The handle of the form to submit to
data
Record<string, any> required
The form data to submit
fetchOptions
FetchOptions = {}
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to the form submission response
taxonomyTerms()
See the Statamic REST API documentation for taxonomy terms for more information.
Fetches terms from a specific taxonomy.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("taxonomyTerms", "tags"),
() => api.taxonomyTerms("tags"),
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("taxonomyTerms", "tags"),
() => api.taxonomyTerms("tags", { fields: ["title"] }),
);
</script>
Type Definition
function fetchTaxonomyTerms<DataType extends Record<string, any> = any>(
taxonomyHandle: string,
params: Partial<StatamicApiParamsMultiple<DataType>> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseSingle<DataType>[]>;
Params
taxonomyHandle
string required
The handle of the taxonomy to fetch terms from
params
Partial<StatamicApiParamsMultiple<DataType>>
Optional parameters for filtering, pagination, and field selection
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseSingle<DataType>[]>
Promise that resolves to the taxonomy terms
taxonomyTerm()
See the Statamic REST API documentation for a specific taxonomy term for more information.
Fetches a specific taxonomy term by its slug.
Usage
Basic example
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("taxonomyTerm", "tags", "example-tag-1"),
() => api.taxonomyTerm("tags", "example-tag-1"),
);
</script>
Type Definition
function fetchTaxonomyTerm<DataType extends Record<string, any> = any>(
taxonomyHandle: string,
termSlug: string,
params: Partial<StatamicApiParamsSingle> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseSingle<DataType>>;
Params
taxonomyHandle
string required
The handle of the taxonomy containing the term
termSlug
string required
The slug of the term to fetch
params
Partial<StatamicApiParamsSingle>
Optional parameters for field selection and other options
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseSingle<DataType>>
Promise that resolves to the taxonomy term data
graphql()
Executes a GraphQL query against the Statamic API.
Usage
Basic example
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("graphql", "ping"),
() => api.graphql("MyQuery { ping }"),
);
</script>
Type Definition
function fetchGraphql(
query: string,
fetchOptions: Omit<FetchOptions, "query"> = {},
): Promise<Record<string, any>>;
Params
query
string required
The GraphQL query string to execute
fetchOptions
Omit<FetchOptions, 'query'>
Optional $fetch options
Return Value
Promise<Record<string, any>>
Promise that resolves to the GraphQL response
redirects()
Fetches all redirects for the current site.
This is by default a server side method and is therefore cached. When you need to fetch the redirects on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("redirects", "all"),
() => api.redirects(),
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("redirects", "all"),
() => api.redirects({}, { baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
function fetchRedirects(
params: Record<string, any> = {},
fetchOptions: Omit<FetchOptions, "params"> = {},
): Promise<StatamicApiResponseRedirects>;
Params
params
Record<string, any> = {}
Optional parameters for filtering
fetchOptions
Omit<FetchOptions, 'params'>
Optional $fetch options
Return Value
Promise<StatamicApiResponseRedirects>
Promise that resolves to the redirects data
sitemapUrls()
Fetches the sitemap URLs.
This is by default a server side method and is therefore cached. When you need to fetch the sitemap URLs on the client side, you can provide the baseURL option to the fetchOptions parameter to use the client side route instead.
Do note that you will most likely need to do some additional processing to the data to get the sitemap URLs in the correct format, since it will return a XML sitemap response.
Usage
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("sitemapUrls", "all"),
() => api.sitemapUrls(),
);
</script>
<script setup lang="ts">
const api = useStatamicApi();
const { data } = await useAsyncData(
useStatamicCacheKey("sitemapUrls", "all"),
() => api.sitemapUrls({ baseURL: process.env.NUXT_PUBLIC_STATAMIC_URL }),
);
</script>
Type Definition
function fetchSitemapUrls(
fetchOptions: FetchOptions = {},
): Promise<StatamicSitemapUrl[]>;
Params
fetchOptions
FetchOptions = {}
Optional $fetch options
Return Value
Promise<StatamicSitemapUrl[]>
Promise that resolves to the sitemap URLs
Available parameters
Parameters<T>
All the available parameters for the Statamic API, for the different types of requests. You can find which type of parameters are used for each request in the API Reference above.
fields
string[]
The top level fields that should be included in the response.
Example
{ fields: ["id", "title", "content"] }
filter
Record<string, any>
Filter results based on the specified field conditions.
You may specify filters following the pattern:
You may specify filters following the pattern:
{field_name}:{condition}={value}| Condition | Description |
|---|---|
is / equals | Include if field is equal to value. |
not / isnt | Include if field is not equal to value. |
exists / isset | Include if field exists. |
doesnt_exist / is_empty / null | Include if field doesn't exist. |
contains | Include if field contains value. |
doesnt_contain | Include if field doesn't contain value. |
in | Include if field value is in the provided array. |
not_in | Include if field value is not_in the provided array. |
starts_with | Include if field starts with value. |
doesnt_start_with | Include if field doesn't start with value. |
ends_with | Include if field ends with value. |
doesnt_end_with | Include if field doesn't end with value. |
gt | Include if field is greater than value. |
gte | Include if field is greater than or equal to value. |
lt | Include if field is less than value. |
lte | Include if field is less than or equal to value. |
matches / regex | Include if field matches case insensitive regex. |
doesnt_match | Include if field doesn't match case insensitive regex. |
is_alpha | Include if field contains only alphabetical characters. |
is_numeric | Include if field contains only numeric characters. |
is_alpha_numeric | Include if field contains only alphanumeric characters. |
is_url | Include if field is a valid URL. |
is_embeddable | Include if field is an embeddable video URL. |
is_email | Include if field is valid email address. |
is_after | Include if field is after date. |
is_before | Include if field is before date. |
is_numberwang | Include if field is numberwang. |
Example
{ filter: { "title:contains": "awesome", featured: true, } }
sort
string
Sort results based on the specified fields.
Fields can be prexied with a hyphen to sort descending.
Fields can be prexied with a hyphen to sort descending.
{ sort: "fieldName" }
{ sort: "fieldName,anotherfield" }
{ sort: "fieldNameOne,-fieldNameTwo,fieldNameThree" }
{ sort: "-fieldName" }
{ sort: "fieldName->nestedFieldName" }
limit
number
Defaults to
25 - The number of results to fetch per page (paginated).page
number
Defaults to
1 - The page number to fetch.site
string
The site to fetch data from.
This will be automatically handled by the
This will be automatically handled by the
useStatamicSite() composable inside the useStatamicApi() composable.token
string
The token to use for live preview mode.
This will be automatically handled by the
This will be automatically handled by the
useStatamicPreviewMode() composable inside the useStatamicApi() composable.max_depth
number
The maximum nesting depth of the navigation tree.
uri
string
The URI to fetch data from.