View our GitHub

Please visit sails-docs on GitHub to view documentation on your mobile device.

Edit Page

Add (Blueprint)

Add a foreign record (e.g. a comment) to one of this record's collection associations (e.g. "comments").

POST /:model/:id/:association/:fk

This action pushes a reference to some other record (the "foreign" record) onto a collection attribute of this record (the "primary" record).

  • If :fk of an existing foreign record is supplied, it will be associated with the primary record.
  • If no :fk is supplied, and the body of the POST contains values for a new record, that record will be created and associated with the primary record.
  • If the collection association within the primary record already contains a reference to the foreign record, this action will be ignored.
  • If the association is 2-way (i.e. reflexive, with "via" on both sides) the association on the foreign record will also be updated.


Parameter Type Details
The parent record's primary key value

e.g. 7
association The name of the collection association

e.g. 'involvedInPurchases'
The id of the foreign record to add to the collection association.

e.g. 47
callback If specified, a JSONP response will be sent (instead of JSON). This is the name of the client-side javascript function to call, passing results as the first (and only) argument

e.g. ?callback=myJSONPHandlerFn


Add purchase #47 to the list of purchases that Dolly (employee #7) has been involved in:

POST /employee/7/involvedInPurchases/47
Expected response

This will return "Dolly", the primary record:

  "involvedInPurchases": [
      "amount": 10000,
      "createdAt": "2014-08-03T01:50:33.898Z",
      "updatedAt": "2014-08-03T01:51:08.227Z",
      "id": 47,
      "cashier": 7
  "name": "Dolly",
  "createdAt": "2014-08-03T01:16:35.440Z",
  "updatedAt": "2014-08-03T01:51:41.567Z",
  "id": 7
Using jQuery
$.post('/employee/7/involvedInPurchases/47', function (purchases) {
Using Angular
.then(function (purchases) {
Using'/employee/7/involvedInPurchases/47', function (purchases) {
Using cURL
curl http://localhost:1337/employee/7/involvedInPurchases/47 -X "POST"


  • If you'd like to spend some more time with Dolly, a more detailed walkthrough related to the example above is available here.
  • This action is for dealing with plural ("collection") associations. If you want to set or unset a singular ("model") association, just use update.
  • The example above assumes "rest" blueprints are enabled, and that your project contains at least an 'Employee' model with association: involvedInPurchases: {collection: 'Purchase', via: 'cashier'} as well as a Purchase model with association: cashier: {model: 'Employee'}. You'll also need at least an empty PurchaseController and EmployeeController. You can quickly achieve this by running:

    $ sails new foo
    $ cd foo
    $ sails generate api purchase
    $ sails generate api employee

...then editing api/models/Purchase.js and api/models/Employee.js.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.


We wrote a book!

Get early access to the book
with promotion code: mcneildoc

Get the Book