NAV
javascript shell

Introduction

The SiteSails API is organized around REST, it accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

The recommended way to access the API is using the JavaScript client module. You can view code examples to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

// initialize the client module
export const ss = new SiteSailsClient({
  publicApiKey: 'mypublickey',
  adminApiKey: 'myadminkey',
});

# there is no initialization step, you just add the api key parameter:
curl "https://api.sitesails.com/api/v1/nodes/blog?apiKey=mypublickey"

Make sure to replace the dummy keys with your API keys.

SiteSails uses API keys to allow access to the API. You can get the public and admin API key in the dashboard.

SiteSails expects for the API key to be included in all API requests to the server in the apiKey query parameter.

Nodes

Nodes are the main building blocks of SiteSails which hold the data defined in the Section they belong to. For these examples we'll be using a section named Recipes (accessible through recipes slug).

Search Nodes

curl "https://api.sitesails.com/api/v1/nodes/recipes?category=barbecue&pageNumber=1&pageSize=10&lang=en&apiKey=mypublickey"

  const params: NodeSearchParams = {
    category: 'barbecue',
    pageNumber: 1,
    pageSize: 10,
    lang: 'en',
  };

  const recipesPages = await ss
    .nodes('recipes')
    .search(params);

The above command returns JSON structured like this:

[
  {
    "id": 182,
    "slug": "fall-apart-bourbon-ribs",
    "slugs": {
      "en": "fall-apart-bourbon-ribs"
    },
    "sectionId": 2,
    "languageId": "en",
    "createdAt": "2020-10-29T06:33:00Z",
    "updatedAt": "2020-10-29T06:33:00Z",
    "category": {
      "id": 2670,
      "slug": null,
      "name": "Barbecue",
      "itemCount": null
    },
    "data": {
      "title": "Fall-apart bourbon ribs",
      "description": "Few things are more satisfying to eat than tender, sticky ribs. This recipe adds a bourbon kick to the sweet glaze, providing a real depth of flavour. It will be a family favourite.",
      "text": null,
      "author": "John Doe",
      "duration": "180",
      "allergens": [],
      "servingSize": "5"
    },
    "seoMetadata": null,
    "image": {
      "id": 170,
      "isMain": true,
      "name": "3402.png",
      "url": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
      "smallUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
      "mediumUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
      "originalFileId": 723,
      "mediumFileId": 723,
      "smallFileId": 723
    },
    "images": null,
    "contents": null,
    "connectionStats": null,
    "connections": {},
    "event": null,
    "product": null,
    "publishable": {
      "isPublished": true,
      "publishedFrom": "2020-10-29T06:33:00",
      "publishedTo": null
    },
    "collectionItems": null,
    "subsections": null
  }
]

This endpoint returns multiple nodes for a defined section.

HTTP Request

GET https://api.sitesails.com/api/v1/nodes/:section

Query Parameters

Parameter Default Description
pageNumber 1
pageSize 20
lang client default language that the results will be returned for
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned
connectedBy returns only the nodes having a connection to member defined by connectionsFor
search returns only nodes containing the search string
sortBy apiName of the field to sort by
sortDirection asc asc (ascending) or desc (descending)
filters returns only nodes containing the defined field values
include defines what will be returned for each node. A combination of unpublished, content, contents, images, onlytranslated

Get Node

# Get by ID...
curl "https://api.sitesails.com/api/v1/nodes/recipes/182?lang=en&apiKey=mypublickey"

# ..or slug
curl "https://api.sitesails.com/api/v1/nodes/recipes/fall-apart-bourbon-ribs?lang=en&apiKey=mypublickey"

  const params: NodeGetParams = {
    lang: 'en',
  };

  // Get by id...
  const recipe = await ss
    .nodes('recipes')
    .get(182, params);

  // ...or slug
  const recipe = await ss
    .nodes('recipes')
    .get('fall-apart-bourbon-ribs', params);

The above command returns JSON structured like this:

{
  "id": 182,
  "slug": "fall-apart-bourbon-ribs",
  "slugs": {
    "en": "fall-apart-bourbon-ribs"
  },
  "sectionId": 2,
  "languageId": "en",
  "createdAt": "2020-10-29T06:33:00Z",
  "updatedAt": "2020-10-29T06:33:00Z",
  "category": {
    "id": 2670,
    "slug": null,
    "name": "Barbecue",
    "itemCount": null
  },
  "data": {
    "title": "Fall-apart bourbon ribs",
    "description": "Few things are more satisfying to eat than tender, sticky ribs. This recipe adds a bourbon kick to the sweet glaze, providing a real depth of flavour. It will be a family favourite.",
    "text": "<p><strong>STEP 1</strong></p><p>Heat the oven to 180C/fan 160C/gas 4. Put the rib pieces, flesh side down, in a single layer in a large roasting tin. Pour over enough boiling water to just cover, then add the spices. Tightly cover with foil and cook for 2 hours.</p><p><strong>STEP 2</strong></p><p>Put all the glaze ingredients in a pan with 2 tbsp water and heat until melted together.</p><p><strong><img src=\"https://api.sitesails.com/public/58cbde20-5bb3-4c69-86cf-adf341e1b344-1925.png\" class=\"ss__image-align-center\">STEP 3</strong></p><p>Take the ribs out the oven and turn it up to 200C/fan 180C/gas 6. Drain all the liquid from the tin. Turn the ribs flesh side up and baste with the glaze. Roast for 30 minutes, adding more glaze halfway through until the ribs are sticky and shiny. Serve, making sure there are plenty of napkins for everyone.</p>",
    "author": "John Doe",
    "duration": "180",
    "allergens": [],
    "servingSize": "5"
  },
  "seoMetadata": null,
  "image": {
    "id": 170,
    "isMain": true,
    "name": "3402.png",
    "url": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "smallUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "mediumUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "originalFileId": 723,
    "mediumFileId": 723,
    "smallFileId": 723
  },
  "images": [{
    "id": 170,
    "isMain": true,
    "name": "3402.png",
    "url": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "smallUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "mediumUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "originalFileId": 723,
    "mediumFileId": 723,
    "smallFileId": 723
  }, {
    "id": 172,
    "isMain": false,
    "name": "baby-back-ribs-whiskey-bbq-sauce2-720x540.jpg",
    "url": "https://api.sitesails.com/public/e467936b-6302-4bf6-a69e-afc07b3fb89b-baby-back-ribs-whiskey-bbq-sauce2-720x540.jpg",
    "smallUrl": "https://api.sitesails.com/public/e467936b-6302-4bf6-a69e-afc07b3fb89b-small-baby-back-ribs-whiskey-bbq-sauce2-720x540.jpg",
    "mediumUrl": "https://api.sitesails.com/public/e467936b-6302-4bf6-a69e-afc07b3fb89b-medium-baby-back-ribs-whiskey-bbq-sauce2-720x540.jpg",
    "originalFileId": 845,
    "mediumFileId": 847,
    "smallFileId": 846
  }, {
    "id": 173,
    "isMain": false,
    "name": "e3dcd5ea-10b3-41c2-9288-053f804d3ce8.jpg",
    "url": "https://api.sitesails.com/public/6b640210-4fa3-4eea-8225-332ce7d4745e-e3dcd5ea-10b3-41c2-9288-053f804d3ce8.jpg",
    "smallUrl": "https://api.sitesails.com/public/6b640210-4fa3-4eea-8225-332ce7d4745e-small-e3dcd5ea-10b3-41c2-9288-053f804d3ce8.jpg",
    "mediumUrl": "https://api.sitesails.com/public/6b640210-4fa3-4eea-8225-332ce7d4745e-medium-e3dcd5ea-10b3-41c2-9288-053f804d3ce8.jpg",
    "originalFileId": 848,
    "mediumFileId": 850,
    "smallFileId": 849
  }],
  "contents": [{
    "id": 375,
    "languageId": "en",
    "slug": "fall-apart-bourbon-ribs",
    "data": {
      "title": "Fall-apart bourbon ribs",
      "description": "Few things are more satisfying to eat than tender, sticky ribs. This recipe adds a bourbon kick to the sweet glaze, providing a real depth of flavour. It will be a family favourite.",
      "text": "<p><strong>STEP 1</strong></p><p>Heat the oven to 180C/fan 160C/gas 4. Put the rib pieces, flesh side down, in a single layer in a large roasting tin. Pour over enough boiling water to just cover, then add the spices. Tightly cover with foil and cook for 2 hours.</p><p><strong>STEP 2</strong></p><p>Put all the glaze ingredients in a pan with 2 tbsp water and heat until melted together.</p><p><strong><img src=\"https://api.sitesails.com/public/58cbde20-5bb3-4c69-86cf-adf341e1b344-1925.png\" class=\"ss__image-align-center\">STEP 3</strong></p><p>Take the ribs out the oven and turn it up to 200C/fan 180C/gas 6. Drain all the liquid from the tin. Turn the ribs flesh side up and baste with the glaze. Roast for 30 minutes, adding more glaze halfway through until the ribs are sticky and shiny. Serve, making sure there are plenty of napkins for everyone.</p>"
    }
  }],
  "connectionStats": null,
  "connections": {},
  "event": null,
  "product": null,
  "publishable": {
    "isPublished": true,
    "publishedFrom": "2020-10-29T06:33:00",
    "publishedTo": null
  },
  "collectionItems": [],
  "subsections": {}
}

This endpoint returns a single Node for a section, either by looking up its ID or slug.

HTTP Request

GET https://api.sitesails.com/api/v1/nodes/:section/:node

Query Parameters

Parameter Default Description
lang client default language that the results will be returned for
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned

Search Categories

curl "https://api.sitesails.com/api/v1/nodes/recipes/categories?pageNumber=1&pageSize=10&lang=en&apiKey=mypublickey"

  const params: NodeSearchParams = {
    pageNumber: 1,
    pageSize: 10,
    lang: 'en',
  };

  const categoriesPages = await ss
    .nodes('recipes')
    .categories(params);

The above command returns JSON structured like this:

[
  {
    "id": 2711,
    "slug": "integral",
    "slugs": {
      "en": "integral"
    },
    "sectionId": 38,
    "languageId": "en",
    "createdAt": "2020-12-26T22:46:51.866374Z",
    "updatedAt": "2020-12-26T22:46:51.866374Z",
    "category": {
      "id": null,
      "slug": null,
      "name": null,
      "itemCount": 0
    },
    "data": {
      "description": null,
      "text": null,
      "name": "Integral"
    },
    "seoMetadata": null,
    "image": null,
    "images": null,
    "contents": null,
    "connectionStats": null,
    "connections": {},
    "event": null,
    "product": null,
    "publishable": {
      "isPublished": true,
      "publishedFrom": "2020-01-01T00:00:00",
      "publishedTo": null
    },
    "collectionItems": null,
    "subsections": null
  }
]

This endpoint allows you to list all categories of a particular section.

HTTP Request

GET https://api.sitesails.com/api/v1/nodes/:section/categories

Query Parameters

Parameter Default Description
pageNumber 1
pageSize 20
lang client default language that the results will be returned for
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned
connectedBy returns only the nodes having a connection to member defined by connectionsFor
search returns only nodes containing the search string
sortBy apiName of the field to sort by
sortDirection asc asc (ascending) or desc (descending)
filters returns only nodes containing the defined field values
include defines what will be returned for each node. A combination of unpublished, content, contents, images, onlytranslated

Get Category

# Get by ID...
curl "https://api.sitesails.com/api/v1/nodes/recipes/category/2711?lang=en&apiKey=mypublickey"

# ..or slug
curl "https://api.sitesails.com/api/v1/nodes/recipes/category/integral?lang=en&apiKey=mypublickey"

  const params: NodeGetParams = {
    lang: 'en',
  };

  // Get by id...
  const category = await ss
    .nodes('recipes')
    .category(182, params);

  // ...or slug
  const category = await ss
    .nodes('recipes')
    .category('fall-apart-bourbon-ribs', params);

The above command returns JSON structured like this:

{
  "id": 2711,
  "slug": "integral",
  "slugs": {
    "en": "integral"
  },
  "sectionId": 38,
  "languageId": "en",
  "createdAt": "2020-12-26T22:46:51.866374Z",
  "updatedAt": "2020-12-26T22:46:51.866374Z",
  "category": {
    "id": null,
    "slug": null,
    "name": null,
    "itemCount": 0
  },
  "data": {
    "title": null,
    "description": null,
    "text": null,
    "name": "Integral"
  },
  "seoMetadata": null,
  "image": null,
  "images": [],
  "contents": [{
    "id": 4494,
    "languageId": "en",
    "slug": null,
    "data": {
      "description": null,
      "text": null,
      "name": "Integral"
    }
  }],
  "connectionStats": null,
  "connections": {},
  "event": null,
  "product": null,
  "publishable": {
    "isPublished": true,
    "publishedFrom": "2020-01-01T00:00:00",
    "publishedTo": null
  },
  "collectionItems": [],
  "subsections": {}
}

This endpoint allows you to fetch a single category for the given section by looking up either its ID or slug.

HTP Request

GET https://api.sitesails.com/api/v1/nodes/:section/categories/:category

Query Parameters

Parameter Default Description
lang client default language that the results will be returned for
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned

Connections

Connections can be thought of as subsections, or enhancements of sections. For the following examples we'll be using the Reviews connection added to our Recipes section, accessed through the reviews slug.

Search Connections

curl "https://api.sitesails.com/api/v1/connections/reviews?pageNumber=1&pageSize=10&lang=en&apiKey=mypublickey"

  const params: ConnectionSearchParams = {
    node: 182,
    lang: 'en',
  };

  const reviewsPages = await ss
    .connections('reviews')
    .search(params);

The above command returns JSON structured like this:

[
  {
    "id": 7534,
    "parentId": null,
    "nodeId": 182,
    "nodeName": "Fall-apart bourbon ribs",
    "nodeSlug": "fall-apart-bourbon-ribs",
    "nodeImageUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
    "memberId": 1724,
    "memberFirstName": "John",
    "memberLastName": "Doe",
    "memberAvatarUrl": null,
    "createdAt": "03/15/2021 18:57:21",
    "data": {
      "text": null,
      "score": 0,
      "title": null,
      "verifiedAt": null
    },
    "languages": ["en"],
    "contents": null
  }
]

This endpoint allows you to search connections for a node, either by ID or slug.

HTTP Request

GET https://api.sitesails.com/api/v1/connections/:connection

Query Parameters

Parameter Default Description
lang client default language that the results will be returned for
node node ID or slug to look up connections for
memberId look for connections created by a member
verified only fetches verified connections

Add Connection

const params: ConnectionAddParams = {
  memberToken: 'memberToken',
  nodeId: 182,
  lang: 'en',
  data: {
    text: 'Review',
  },
};

const addedConnection = await ss
  .connections('reviews')
  .add(params);

The above command returns JSON structured like this:

{
  "id": 7534,
  "parentId": null,
  "nodeId": 182,
  "nodeName": "Fall-apart bourbon ribs",
  "nodeSlug": "fall-apart-bourbon-ribs",
  "nodeImageUrl": "https://api.sitesails.com/public/de1f9510-68ac-4cf8-98f0-1d87198f5050-3402.png",
  "memberId": 1724,
  "memberFirstName": "John",
  "memberLastName": "Doe",
  "memberAvatarUrl": null,
  "createdAt": "03/15/2021 18:57:21",
  "data": {
    "text": "Review",
    "score": 0,
    "title": null,
    "verifiedAt": null
  },
  "languages": ["en"],
  "contents": null
}

This endpoint allows you to create a connection to a Node, given the current member token and the data it requires.

HTTP Request

POST https://api.sitesails.com/api/v1/connections/:connection

Query Parameters

Parameter Default Description
lang client default language that the results will be returned for
nodeId node ID or slug to assign the connection to
memberToken member who is creating the connection
data all the connection data, be it score, text, or anything it requires

Remove Connection

const params: ConnectionAddParams = {
  memberToken: 'memberToken',
  nodeId: 182,
};

await ss
  .connections('reviews')
  .remove(params);

The above command doesn't return any data

This endpoint allows you to remove a previously added connection by a member.

Query Parameters

Parameter Default Description
nodeId node ID or slug to delete the connection from
memberToken member who is deleting the connection

Collections

Collections are lists of section items. For example, following the Recipes example we've been using, collections could be Recipe Books that contained multiple recipes. Or recipes for Christmas, recipes for dinner, and so on. For the examples below we'll be using Special Occasions collections, accessible through special-occasions slug.

Search collections

curl "https://api.sitesails.com/api/v1/collections/recipes/special-occasions?pageNumber=1&pageSize=20&lang=en&apiKey=mypublickey"

const params: CollectionSearchParams = {
  pageNumber: 1,
  pageSize: 20,
  lang: 'en',
};

const collectionsPages = await ss
  .collections('recipes', 'special-occasions')
  .search(params);

The above command returns JSON structured like this:

[
  {
    "id": 6988,
    "slug": "christmas",
    "slugs": {
      "en": "christmas"
    },
    "sectionId": 77,
    "languageId": "en",
    "createdAt": "2021-03-15T19:45:29.989824Z",
    "updatedAt": "2021-03-15T19:45:29.989824Z",
    "category": {
      "id": 2670,
      "slug": null,
      "name": "Barbecue",
      "itemCount": null
    },
    "data": {
      "title": "Christmas",
      "description": "",
      "text": null
    },
    "seoMetadata": "[]",
    "image": null,
    "images": null,
    "contents": null,
    "connectionStats": null,
    "connections": {},
    "event": null,
    "product": null,
    "publishable": {
      "isPublished": true,
      "publishedFrom": "2021-03-15T18:44:00Z",
      "publishedTo": null
    },
    "collectionItems": null,
    "subsections": null
  }
]

This endpoint allows you to list and search collections of a section. In the example we're looking for the first twenty Special Occasions recipes collections. Bear in mind that without informing the include parameter in the request, the endpoint will not return the collection items to save on data transfer.

HTTP Request

GET https://api.sitesails.com/api/v1/collections/:section/:collection

Query Parameters

Parameter Default Description
pageNumber 1
pageSize 20
lang client default language that the results will be returned for
search returns only nodes containing the search string
sortBy apiName of the field to sort by
sortDirection asc asc (ascending) or desc (descending)
filters returns only nodes containing the defined field values
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned
include defines what will be returned for each node. A combination of unpublished, content, contents, images, onlytranslated, collectionitems

Get Collection

# Get by ID...
curl "https://api.sitesails.com/api/v1/collections/recipes/special-occasions/6988?lang=en&apiKey=mypublickey"

# ..or slug
curl "https://api.sitesails.com/api/v1/collections/recipes/special-occasions/christmas?lang=en&apiKey=mypublickey"

  const params: NodeGetParams = {
    lang: 'en',
    include: 'collectionitems',
  };

  // Get by id...
  const collection = await ss
    .collections('recipes', 'special-occasions')
    .get(6988, params);

  // ...or slug
  const collection = await ss
    .collections('recipes', 'special-occasions')
    .get('christmas', params);

The above command returns JSON structured like this:

{
  "id": 6988,
  "slug": "christmas",
  "slugs": {
    "en": "christmas"
  },
  "sectionId": 77,
  "languageId": "en",
  "createdAt": "2021-03-15T19:45:29.989824Z",
  "updatedAt": "2021-03-15T19:45:29.989824Z",
  "category": {
    "id": 2670,
    "slug": null,
    "name": "Barbecue",
    "itemCount": null
  },
  "data": {
    "title": "Christmas",
    "description": "",
    "text": ""
  },
  "seoMetadata": "[]",
  "image": null,
  "images": [],
  "contents": [{
    "id": 23491,
    "languageId": "en",
    "slug": "christmas",
    "data": {
      "title": "Christmas",
      "description": "",
      "text": ""
    }
  }],
  "connectionStats": null,
  "connections": {},
  "event": null,
  "product": null,
  "publishable": {
    "isPublished": true,
    "publishedFrom": "2021-03-15T18:44:00Z",
    "publishedTo": null
  },
  "collectionItems": [{
    "id": 397,
    "position": 1,
    "nodeId": 182,
    "nodeSlug": "fall-apart-bourbon-ribs",
    "nodeName": "Fall-apart bourbon ribs",
    "node": null
  }],
  "subsections": {}
}

This endpoint returns a single Collection list with all its data either by looking up its ID or slug.

HTTP Request

GET https://api.sitesails.com/api/v1/collections/:section/:collection/:id

Query Parameters

Parameter Default Description
lang client default language that the results will be returned for
connections connections that will be returned for each node
connectionStats connection statistics that will be returned for each node
connectionsFor member id for which the connections will be returned
include defines what will be returned for each node. A combination of unpublished, content, contents, images, onlytranslated, collectionitems

Members

Members are users registered to the website.

Current user

const currentUser = await ss
  .members(memberToken)
  .get();

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": false
}

This endpoint returns the current logged in member based on the provided memberToken.

HTTP Request

GET https://api.sitesails.com/api/v1/members/me

Query Parameters

No query parameters are available for this endpoint.

Get member

// Get by id...
const member = await ss
  .members()
  .get(1724);

// ...or by e-mail
const member = await ss
  .members()
  .get('[email protected]');

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": false
}

This endpoint returns the user with the specified ID or e-mail address

HTTP Request

GET https://api.sitesails.com/api/v1/members/:id

Query Parameters

No query parameters are available for this endpoint.

Register

const params: MemberRegistrationParams = {
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe',
  password: 'supersecret',
  hasNotificationConsent: true,
};

const member = await ss
  .members()
  .register(params);

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": true,
  "isRegistration": true,
  "token": "memberToken"
}

This endpoint allows you to register a new member to the website.

HTTP Request

POST https://api.sitesails.com/api/v1/members/register

Request Body

Parameter Default Description
email member email
firstName member first name
lastName member last name
password member password
hasNotificationConsent optional boolean switching notifications on and off

Login

const params: MemberLoginParams = {
  email: '[email protected]',
  password: 'supersecret',
};

const member = await ss
  .members()
  .login(params);

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": true,
  "token": "memberToken"
}

This endpoint allows a member to log in using its e-mail address and password.

HTTP Request

POST https://api.sitesails.com/api/v1/members/authenticate

Request Body

Parameter Default Description
email member email
password member password

Social Login

const params: MemberSocialLoginParams = {
  idToken: 'token',
  accessToken: 'access',
  provider: 'google',
};

const member = await ss
  .members()
  .socialLogin(params);

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": true,
  "token": "memberToken"
}

This endpoint allows a member to log in using an external social provider. Currently only Google sign in is supported.

HTTP Request

POST https://api.sitesails.com/api/v1/members/authenticate-social

Request Body

Parameter Default Description
idToken Google's OAuth ID Token
accessToken Google's OAuth Access Token
provider google Currently only Google is supported

Update Member

const params: MemberUpdateParams = {
  firstName: 'John',
  lastName: 'Doe',
  hasNotificationConsent: false,
};

const member = await ss
  .members(memberToken)
  .update(params);

The command above returns JSON structured like this:

{
  "id": 1724,
  "memberRoleId": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "activatedAt": "2021-03-15T17:57:11.526553",
  "createdAt": "2021-03-15T18:57:11.53046",
  "updatedAt": "2021-03-15T17:57:12.088199",
  "data": {},
  "avatarUrl": null,
  "hasNotificationConsent": false,
  "token": "memberToken"
}

This endpoint allows you to update member data such as name and notification consent.

HTTP Request

PATCH https://api.sitesails.com/api/v1/members/me

Request Body

Parameter Default Description
firstName member first name
lastName member last name
hasNotificationConsent user enabled notifications

Update Data

const data: Record<string, any> = {
  anyRelevantData: ['anyValue'],
};

const memberData = await ss
  .members(memberToken)
  .setData(data);

The command above returns the same data sent to it

This endpoint allows you to set and update custom member data, where you can store anything the website needs such as user settings and so on.

HTTP Request

POST https://api.sitesails.com/api/v1/members/me/data

Request Body

Parameter Default Description
data any JSON-serializable data

Update Avatar

await ss
  .members(memberToken)
  .updateAvatar(userSelectedFile, optionalFileName);

The command above doesn't return any data

This endpoint allows you to set and update the member's avatar optionally providing a file name to be used.

HTTP Request

POST https://api.sitesails.com/api/v1/members/me/avatar

Parameters

Parameter Default Description
file user-selected image file
fileName new file name for the avatar

JavaScript Client Params

Here are some common parameters that can be passed to many of the data-fetching methods listed above.

Transformations

  const transformNode = (response: Node) => ({
    id: response.id,
    slug: response.slug,
  });

  const recipesPages = await ss
    .nodes('recipes')
    .search(params, transformNode);

The above code would map the transformation function to all returned Nodes, producing the following code:

[
  {
    "id": 182,
    "slug": "fall-apart-bourbon-ribs"
  }
]

This allows you to transform data beforehand as it is received by the SiteSails module. In this example we're merely cutting out many of the data and keeping only id and slug but you could, for instance, have all dates parsed automatically.

Methods

Transformations are supported in the following methods as the last parameter:

Errors

The SiteSails API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.
javascript shell