API docs by Redocly

Crafter Engine (4.1.9)

Download OpenAPI specification:Download

E-mail: info@craftercms.org License: GPL 3.0

Crafter Engine API

CrafterCMS - Engine

content

Content retrieval operations

Get Item

Get an Item from the content store.
This API is used to get pages, components and folders. It returns the content and other metadata such as url, descriptorUrl, folder flag, and extra properties

Note: This API also returns 'disabled' items when Crafter Engine is in preview mode to support authoring use cases.

query Parameters
url
required
string

The item’s url (e.g. /site/website/index.xml)

flatten
boolean

Indicates if included descriptors should be flattened

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
Example
{
  • "name": "website",
  • "url": "/site/website",
  • "descriptorUrl": "/site/website.meta.xml",
  • "descriptorDom": null,
  • "properties": null,
  • "folder": true
}

Get Children

Get the list of Items directly under a folder in the content store.

query Parameters
url
required
string

The folder’s url (e.g. /site/website/index.xml)

flatten
boolean

Indicates if included descriptors should be flattened

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get Tree

Get the complete Item hierarchy under the specified folder in the content store.

query Parameters
url
required
string

The folder’s url (e.g. /site/website/index.xml)

depth
integer

Amount of levels to include (unlimited by default)

flatten
boolean

Indicates if included descriptors should be flattened

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "url": "string",
  • "descriptorUrl": "string",
  • "descriptorDom": { },
  • "properties": "string",
  • "folder": true
}

Query (GET)

Performs a query in the GraphQL instance of the current site resolved for the request.

Note:
The query string must be a valid GraphQL query as described in the official docs

query Parameters
query
required
string
Example: query={page_article{items{title_t}}}

The GraphQL query

operationName
string

The GraphQL operation name

variables
string

A JSON object containing variables for the query

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Query (POST)

Performs a query in the GraphQL instance of the current site resolved for the request.

Note:
The query string must be a valid GraphQL query as described in the official docs

query Parameters
crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Request Body schema: application/json

Search Parameters

query
required
string

The GraphQL query

variables
object

A JSON object containing variables for the query

operationName
string

Name you give to your query

Required when there are multiple operations in the document (query)

Responses

Request samples

Content type
application/json
{
  • "query": "query ArticlesByAuthor($author:String) { page_article { total items { title_t author_s(filter:{equals:$author}) date_dt } } }",
  • "variables": {
    },
  • "operationName": "ArticlesByAuthor"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

navigation

Navigation and structure operations

Breadcrumb

Returns the navigation items that form the breadcrumb for the specified store URL.

query Parameters
url
required
string

The URL used to build the breadcrumb

root
string

The starting point of the breadcrumb

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tree

Returns the navigation tree with the specified depth for the specified store URL.

query Parameters
url
required
string
Example: url=/site/website

The root folder of the tree

depth
integer
Example: depth=2

The depth of the tree (defaults to 1)

currentPageUrl
string

The URL of the current page

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "label": "Home",
  • "url": "/",
  • "active": false,
  • "subItem": [
    ]
}

Transform

Transforms a URL, based on the current site’s configuration.

query Parameters
url
required
string
Example: url=/site/website/style/index.xml

The URL to be transformed

transformerName
required
string
Example: transformerName=storeUrlToRenderUrl

The name of the transformer to apply

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
"/style"

search

Search operations

Search

Performs a search operation in the OpenSearch index of the current site resolved for the request and optional other indexes. See Multi-index Query for more information on performing a multiple index search.

Note:
The request body must be a valid OpenSearch JSON query as described in the official docs

query Parameters
index
string

Comma separated list of index names to be searched in addition to the current site

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Request Body schema: application/json

User entity to create

_source
string
size
integer
query
object

Responses

Request samples

Content type
application/json
{
  • "_source": "localId",
  • "size": 1,
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "took": 41,
  • "timed_out": false,
  • "_shards": {
    },
  • "hits": {
    }
}

cache

Cache operations

Clear content cache

Clear the content cache scope and the Freemarker cache for the current site context.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "message": "Cache clear for site 'sample' started"
}

Statistics

Get the statistics for all cache scopes for the current site context.

Note:
The result of this call can change based on the configuration of the system, for example when Crafter Engine is configured in preview mode the cache will be disabled and the result will always be an empty object. There could be also different statistics returned depending on the cache implementation that is being used.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "size": 17,
  • "localHeapSize": 17,
  • "localOffHeapSize": 0,
  • "localDiskSize": 0,
  • "cacheHitRatio": 1,
  • "cacheHitCount": 4,
  • "cacheMissCount": 25,
  • "cacheMissExpiredCount": 0,
  • "cacheMissNotFoundCount": 25
}

context

Project/site context operations

Get the ID for the site context

Get the ID for the site context resolved for the current request, the value returned will depend on the SiteResolver implementation used.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "id": "405ffc233d075b010536bd2eb786b86c"
}

Get the site context status

Get the status for the site context resolved for the current request, the value returned will depend on the SiteResolver implementation used.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "status": "READY"
}

Destroy the site context

Destroy the site context resolved for the current request. Destroying the context involves clearing the cache, destroying any loaded configuration and Spring beans for the site, and destroying the Groovy classloader for the site.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "message": "Site context for 'sample' destroyed. Will be recreated on next request"
}

Rebuild the site context

Rebuild the site context resolved for the current request, which means destroying and then creating the context again.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "message": "Started rebuild for site context for 'sample'"
}

Rebuild all site contexts

Rebuild all site contexts currently found in the registry

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

Responses

Response samples

Content type
application/json
{
  • "message": "Started rebuild of all site contexts"
}

Rebuild GraphQL Schema

Rebuild the GraphQL schema for the site context resolved for the current request.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "message": "Rebuild of GraphQL schema started for 'sample'"
}

Reload the mappings

Reload the mappings used to resolve sites by Crafter Engine. This endpoint is only available when Crafter Engine is in mapped multi-tenant mode.

query Parameters
crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "message": "Mappings reloaded"
}

monitoring

Monitoring operations

Get Memory Stats

Returns the Crafter Engine JVM memory details.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "totalJvmMemory": 2017984512,
  • "freeJvmMemory": 1113921056,
  • "maxJvmMemory": 3817865216,
  • "totalOsMemory": 17179869184,
  • "freeOsMemory": 2669301760,
  • "totalSwapMemory": 2147483648,
  • "freeSwapMemory": 1026555904
}

Get Status

Returns the Crafter Engine JVM status details.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "uptime": 2017984512,
  • "startup": "2019-03-07T21:29:11.049Z"
}

Get Version

Returns the Crafter Engine JVM status details.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "packageName": "Crafter Engine",
  • "packageVersion": "4.0.3-SNAPSHOT",
  • "packageBuild": "48d29a56c6011f2908fb160f7648f66785d44b81",
  • "packageBuildDate": "2023-03-08T21:53:22.558Z",
  • "osName": "Mac OS X",
  • "osVersion": "11.2",
  • "osArch": "x86_64",
  • "javaVersion": "11",
  • "javaVendor": "Oracle Corporation",
  • "javaVm": "OpenJDK 64-Bit Server VM"
}

Get Log Events

Returns all events recorded in the Crafter Engine log for a given site in a specific time period.

query Parameters
site
required
string
Example: site=my-editorial

The name of the site

since
required
integer
Example: since=1396772083660

The time in milliseconds from which events should be fetched

token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

other

Other miscellaneous operations

List jobs

Get a list of all scheduled jobs for the current site.

query Parameters
token
required
string
Example: token=defaultManagementToken

The authorization token

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Profile

Get the current user’s profile from the session, if no profile is set an empty one will be created. Only use it in conjunction with Studio’s Personas.

query Parameters
crafterSite
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "age": 30,
  • "username": "john",
  • "lastname": "doe"
}

Set Profile

Set the current user’s profile, all parameters are added to the profile and stored in the session. Only use it in conjunction with Studio’s Personas.

Note:
Any parameter included in the request will be added as a property for the user profile, if the request is made without any parameter then profile will be cleared.

query Parameters
crafterSite
string
Example: crafterSite=my-editorial

Used to set the project/site value

Request Body schema: application/json
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "username": "john",
  • "lastname": "doe",
  • "age": "30"
}

Response samples

Content type
application/json
{
  • "id": "65de6381b77c310708fbde2665de6381b77c310708fbde26",
  • "username": "john",
  • "lastname": "doe",
  • "age": "30"
}

Preview

Indicates if Engine is configured in preview mode.

query Parameters
crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
{
  • "preview": true
}

Get Component

Get a component.

query Parameters
path
required
string
Example: path=/site/components/features/4be0a368-783c-8f73-7469-63a62636bd4c.xml

Path to the component
(e.g. /site/components/headers/header.xml)

crafterSite
required
string
Example: crafterSite=my-editorial

Used to set the project/site value

Responses

Response samples

Content type
application/json
"<!-- Feature Component -->\\n <article class=\"feature\" data-craftercms-model-path=\"/site/components/features/4be0a368-783c-8f73-7469-63a62636bd4c.xml\" data-craftercms-model-id=\"4be0a368-783c-8f73-7469-63a62636bd4c\" > <span class=\"icon fa-smile far\" data-craftercms-model-path=\"/site/components/features/4be0a368-783c-8f73-7469-63a62636bd4c.xml\" data-craftercms-model-id=\"4be0a368-783c-8f73-7469-63a62636bd4c\" data-craftercms-field-id=\"icon_s\" ></span> <div class=\"content\"> <h3 data-craftercms-model-path=\"/site/components/features/4be0a368-783c-8f73-7469-63a62636bd4c.xml\" data-craftercms-model-id=\"4be0a368-783c-8f73-7469-63a62636bd4c\" data-craftercms-field-id=\"title_t\" > Smile </h3> <div data-craftercms-model-path=\"/site/components/features/4be0a368-783c-8f73-7469-63a62636bd4c.xml\" data-craftercms-model-id=\"4be0a368-783c-8f73-7469-63a62636bd4c\" data-craftercms-field-id=\"body_html\" > <p>Smile, aenean ornare velit lacus, ac varius enim lorem ullamcorper dolore. Proin aliquam facilisis ante interdum. Sed nulla amet lorem feugiat tempus aliquam.</p> </div> </div> </article> <!-- /Feature Component -->"