Backend API
Define data collections and their API behavior. There are many standard models configured by default, such as products, orders, and others. Data models can be created manually in the Swell dashboard under Developer > Models, or may be installed automatically by Swell Apps, thereby expanding your database and available API endpoints.
Refer to the Data model customization guide for details on what you can do with custom models, or see Apps reference to learn how to configure models in Swell Apps.
Fields
id
stringautoUnique identifier for the model.
name
stringrequiredSlug-formatted name of the model.
namespace
stringOptional namespace used in the model's API endpoint, for example "content" results in the endpoint /content/model-name.
version
stringautoSemver-formatted version number. This value is automatically incremented when the model is modified.
label
stringPlural name of a model collection.
singular
stringSingular name of a model record.
public
booleanIndicates the model collection and its values are public by default.
single
booleanIndicates the model only only has one record, instead of a collection.
abstract
booleanIndicates the model can be extended by another model, but cannot be instantiated as a collection.
deprecated
booleanIndicates the model is deprecated and may be removed in a future API version.
storefront
objectStorefront rendering options.
storefront.enabled
booleanIndicates that model data may be displayed in a storefront.
storefront.list
booleanIndicates that model data may be displayed in a storefront list view.
storefront.list_slug
stringThe URL slug used to play modal data in a storefront list view.
storefront.list_title
stringTitle of the page to display a list of records in a storefront.
storefront.list_description
stringA description to display on a storefront list view.
storefront.page
booleanIndicates that model data may be displayed in a storefront page view.
storefront.page_slug_field
stringReference to a URL slug field used to play modal data in a storefront page view.
storefront.page_title_field
stringReference to a title field to display on a storefront page view.
storefront.page_description_field
stringReference to a description field to display on a storefront page view.
extends
stringReference to a parent model to extend properties from.
extends_version
stringautoAutomatically assigned version of an extended model, if applicable.
primary_field
stringThe primary field used to look up records in the model collection.
secondary_field
stringOptional secondary field used to look up records in the model collection.
name_field
stringThe field used as a label for each record by default.
query
objectDefault parameters used when querying the model collection.
query.where
objectDefault filter used when querying the model collection.
query.limit
intDefault number of records to return when querying the model collection.
query.window
intDefault number of pages in a pagination window to calculate when querying the model collection.
query.sort
stringDefault sort parameter used when querying the model collection.
public_permissions
objectRestrictive public query parameters for storefront API calls, if applicable.
public_permissions.scope
stringSet to `account` to limit public permissions to logged-in users only.
public_permissions.fields
array of fieldArray of model fields to allow read access for.
public_permissions.query
objectDefault parameters used when querying the model collection from a public API.
query.where
objectDefault filter used when querying the model collection from a public API.
query.limit
intDefault number of records to return when querying the model collection from a public API.
query.window
intDefault number of pages in a pagination window to calculate when querying the model collection from a public API.
query.sort
stringDefault sort parameter used when querying the model collection from a public API.
public_permissions.input
objectPermissions allowed for write access when called from a public API.
input.scope
stringSet to `account` to limit public permissions to logged-in users only.
input.fields
array of fieldArray of model fields to allow write access for.
content_id
stringID of a content model that defines this model, if applicable.
events
objectModel event configuration. By default, each model is configured with created, updated, and deleted events. Custom events can be automatically triggered based on conditions, or manually triggered via API call.
events.enabled
booleanIndicates that model events will be triggered by the system. Defaults to true.
events.types
array of event_typeEvent types triggered by the system for this model.
event_type.id
stringID of the event. Should be a short ID, such as created, while a fully-qualified event name is referenced in the following format: [model-name].[event-name].
event_type.conditions
objectA query object used to match record values. When matched, the event is triggered. Event conditions support the equivalent format and operators and query filtering.
event_type.fields
array of fieldArray of model fields to include in the event payload, which are sent to webhooks and app functions, as well as recorded in the system /events collection.
event_type.hooks
array of stringEnumerated hooks triggered by the event type. One of: before, after. Hooks allow app functions to block API call processing and modify values before and after an event is triggered.
event_type.hook_timeout
intMaximum time in milliseconds to wait for a hook function to complete before timing out. Defaults to 60000 (60 seconds).
event_type.hook_reject_error
booleanIndicates whether the event will reject requests when an error occurs in a configured hook function. Defaults to false.
event_type.hook_retry_attempts
intMaximum number of times to retry a hook function when an unknown error occurs. Must be between 0 and 3.
events.root
stringautoRoot name of event types used in webhooks. Defaults to a singularized version of the model name, for example product.
fields
objectrequiredModel fields for their properties established for each record of a collection.
Fields are named by the key of each property in this object, for example:
"fields": { "name": { "type": "string" }, ... }
While Swell's API supports working with record values that are not defined by a field, it is strongly recommended to define fields for known values.
fields.field
objectrequiredThe key of each field property is the desired name of the field.
field.type
stringrequiredType of the field. Defaults to string.
Scalar types:
- string
- int
- float
- bool
- date
- currency
- objectid
Complex types:
- array
- object
- collection
- link
- file