Content API

WARNING

Components don’t have API endpoints

As an example, let’s consider the following models:

Content Types:

Restaurant (Collection Type)
Homepage (Single Type)

Components:

Opening hours (category: restaurant)
Title With Subtitle (category: content)
Image With Description (category: content)

`Restaurant` Content Type

`Homepage` Content Type

Fields	Type	Description
title	string	Homepage title
subTitle	string	Homepage sub title
content	dynamiczone	Homepage content

`Opening hours` Component

Fields	Type	Description
day_interval	string	Meta’s day interval
opening_hour	string	Meta’s opening hour
closing_hour	string	Meta’s closing hour

`Title With Subtitle` Component

Fields	Type	Description
title	string	The title
subTitle	string	The sub title

`Image With Description` Component

Fields	Type	Description
image	media	The image file
title	string	The image title
description	text	The image description

Here is the list of endpoints generated for each of your Content Types.

Method	Path	Description
GET	`/{content-type}`	Get the {content-type} content
PUT	`/{content-type}`	Update the {content-type} content
DELETE	`/{content-type}`	Delete the {content-type} content

Examples

Here are some Content Type examples

Single Types

Homepage Content Type

Method	Path	Description
GET	`/homepage`	Get the homepage content
PUT	`/homepage`	Update the homepage content
DELETE	`/homepage`	Delete the homepage content

Contact Content Type

Method	Path	Description
GET	`/contact`	Get the contact content
PUT	`/contact`	Update the contact content
DELETE	`/contact`	Delete the contact content

Collection Types

Restaurant Content Type

Method	Path	Description
GET	`/restaurants`	Get a list of restaurants
GET	`/restaurants/:id`	Get a specific restaurant
GET	`/restaurants/count`	Count restaurants
POST	`/restaurants`	Create a restaurant
DELETE	`/restaurants/:id`	Delete a restaurant
PUT	`/restaurants/:id`	Update a restaurant

Article Content Type

Product Content Type

Method	Path	Description
GET	`/products`	Get a list of products
GET	`/products/:id`	Get a specific product
GET	`/products/count`	Count products
POST	`/products`	Create a product
DELETE	`/products/:id`	Delete a product
PUT	`/products/:id`	Update a product

Category Content Type

Method	Path	Description
GET	`/categories`	Get a list of categories
GET	`/categories/:id`	Get a specific category
GET	`/categories/count`	Count categories
POST	`/categories`	Create a category
DELETE	`/categories/:id`	Delete a category
PUT	`/categories/:id`	Update a category

Tag Content Type

Method	Path	Description
GET	`/tags`	Get a list of tags
GET	`/tags/:id`	Get a specific tag
GET	`/tags/count`	Count tags
POST	`/tags`	Create a tag
DELETE	`/tags/:id`	Delete a tag
PUT	`/tags/:id`	Update a tag

Get entries

Returns entries matching the query filters. You can read more about parameters .

Example request

Example response

[
  {
    "id": 1,
    "name": "Restaurant 1",
    "cover": {
      "id": 1,
      "name": "image.png",
      "hash": "123456712DHZAUD81UDZQDAZ",
      "sha256": "v",
      "ext": ".png",
      "mime": "image/png",
      "size": 122.95,
      "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
      "provider": "local",
      "provider_metadata": null,
      "created_at": "2019-12-09T00:00:00.000Z",
      "updated_at": "2019-12-09T00:00:00.000Z"
    },
    "content": [
      {
        "__component": "content.title-with-subtitle",
        "id": 1,
        "title": "Restaurant 1 title",
        "subTitle": "Cozy restaurant in the valley"
      },
      {
        "__component": "content.image-with-description",
        "id": 1,
        "image": {
          "id": 1,
          "name": "image.png",
          "hash": "123456712DHZAUD81UDZQDAZ",
          "sha256": "v",
          "ext": ".png",
          "mime": "image/png",
          "size": 122.95,
          "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
          "provider": "local",
          "provider_metadata": null,
          "created_at": "2019-12-09T00:00:00.000Z",
          "updated_at": "2019-12-09T00:00:00.000Z"
        },
        "title": "Amazing photography",
        "description": "This is an amazing photography taken..."
      }
    ],
    "opening_hours": [
      {
        "id": 1,
        "day_interval": "Tue - Sat",
        "opening_hour": "7:30 PM",
        "closing_hour": "10:00 PM"
      }
    ]
  }
]

Get an entry

Returns an entry by id.

Example request

GET http://localhost:1337/restaurants/1

Example response

{
  "id": 1,
  "title": "Restaurant 1",
  "cover": {
    "id": 1,
    "name": "image.png",
    "hash": "123456712DHZAUD81UDZQDAZ",
    "sha256": "v",
    "ext": ".png",
    "mime": "image/png",
    "size": 122.95,
    "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
    "provider": "local",
    "provider_metadata": null,
    "created_at": "2019-12-09T00:00:00.000Z",
    "updated_at": "2019-12-09T00:00:00.000Z"
  },
  "content": [
    {
      "__component": "content.title-with-subtitle",
      "id": 1,
      "title": "Restaurant 1 title",
      "subTitle": "Cozy restaurant in the valley"
    },
    {
      "__component": "content.image-with-description",
      "id": 1,
      "image": {
        "id": 1,
        "name": "image.png",
        "hash": "123456712DHZAUD81UDZQDAZ",
        "sha256": "v",
        "ext": ".png",
        "mime": "image/png",
        "size": 122.95,
        "provider": "local",
        "provider_metadata": null,
        "updated_at": "2019-12-09T00:00:00.000Z"
      },
      "title": "Amazing photography",
      "description": "This is an amazing photography taken..."
    }
  ],
  "opening_hours": [
    {
      "id": 1,
      "day_interval": "Tue - Sat",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    }
  ]
}

Count entries

Returns the count of entries matching the query filters. You can read more about parameters here.

Example request

GET http://localhost:1337/restaurants/count

Example response

Create an entry

Creates an entry and returns its value.

Example request

POST http://localhost:1337/restaurants

Example response

{
  "id": 1,
  "title": "restaurant 1",
  "cover": {
    "id": 1,
    "name": "image.png",
    "hash": "123456712DHZAUD81UDZQDAZ",
    "sha256": "v",
    "ext": ".png",
    "mime": "image/png",
    "size": 122.95,
    "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
    "provider": "local",
    "provider_metadata": null,
    "created_at": "2019-12-09T00:00:00.000Z",
    "updated_at": "2019-12-09T00:00:00.000Z"
  },
  "content": [
    {
      "__component": "content.title-with-subtitle",
      "id": 1,
      "title": "Restaurant 1 title",
      "subTitle": "Cozy restaurant in the valley"
    },
    {
      "__component": "content.image-with-description",
      "id": 1,
      "image": {
        "id": 1,
        "name": "image.png",
        "hash": "123456712DHZAUD81UDZQDAZ",
        "sha256": "v",
        "ext": ".png",
        "mime": "image/png",
        "size": 122.95,
        "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
        "provider": "local",
        "provider_metadata": null,
        "created_at": "2019-12-09T00:00:00.000Z",
        "updated_at": "2019-12-09T00:00:00.000Z"
      },
      "title": "Amazing photography",
      "description": "This is an amazing photography taken..."
    }
  ],
  "opening_hours": [
    {
      "id": 1,
      "day_interval": "Tue - Sat",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    }
  ]
}

Partially updates an entry by id and returns its value. Fields that aren’t sent in the query are not changed in the db. Send a null value if you want to clear them.

Example request

PUT http://localhost:1337/restaurants/1

{
  "title": "Restaurant 1",
  "content": [
    {
      "__component": "content.title-with-subtitle",
      // editing one of the previous item by passing its id
      "id": 2,
      "title": "Restaurant 1 title",
      "subTitle": "Cozy restaurant in the valley"
    },
    {
      "__component": "content.image-with-description",
      "image": 1, // user form data to upload the file or an id to reference an exisiting image
      "title": "Amazing photography",
      "description": "This is an amazing photography taken..."
    }
  ],
  "opening_hours": [
    {
      // adding a new item
      "day_interval": "Sun",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    },
    {
      // editing one of the previous item by passing its id
      "id": 1,
      "day_interval": "Mon - Sat",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    }
  ]
}

Example response

{
  "id": 1,
  "title": "Restaurant 1",
  "cover": {
    "id": 1,
    "name": "image.png",
    "hash": "123456712DHZAUD81UDZQDAZ",
    "sha256": "v",
    "ext": ".png",
    "mime": "image/png",
    "size": 122.95,
    "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
    "provider": "local",
    "provider_metadata": null,
    "created_at": "2019-12-09T00:00:00.000Z",
    "updated_at": "2019-12-09T00:00:00.000Z"
  },
  "content": [
    {
      "__component": "content.title-with-subtitle",
      "id": 1,
      "title": "Restaurant 1 title",
      "subTitle": "Cozy restaurant in the valley"
    },
    {
      "__component": "content.image-with-description",
      "id": 2,
      "image": {
        "id": 1,
        "name": "image.png",
        "hash": "123456712DHZAUD81UDZQDAZ",
        "sha256": "v",
        "mime": "image/png",
        "size": 122.95,
        "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
        "provider": "local",
        "provider_metadata": null,
        "created_at": "2019-12-09T00:00:00.000Z",
        "updated_at": "2019-12-09T00:00:00.000Z"
      },
      "title": "Amazing photography",
      "description": "This is an amazing photography taken..."
    }
  ],
  "opening_hours": [
    {
      "id": 1,
      "day_interval": "Mon - Sat",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    },
    {
      "id": 2,
      "day_interval": "Sun",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    }
  ]
}

Delete an entry

Deletes an entry by id and returns its value.

DELETE http://localhost:1337/restaurants/1

Example response

{
  "id": 1,
  "title": "Restaurant 1",
  "cover": {
    "id": 1,
    "hash": "123456712DHZAUD81UDZQDAZ",
    "sha256": "v",
    "ext": ".png",
    "mime": "image/png",
    "size": 122.95,
    "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
    "provider": "local",
    "provider_metadata": null,
    "created_at": "2019-12-09T00:00:00.000Z",
    "updated_at": "2019-12-09T00:00:00.000Z"
  },
  "content": [
    {
      "__component": "content.title-with-subtitle",
      "id": 1,
      "title": "Restaurant 1 title",
      "subTitle": "Cozy restaurant in the valley"
    },
    {
      "__component": "content.image-with-description",
      "id": 2,
      "image": {
        "id": 1,
        "name": "image.png",
        "hash": "123456712DHZAUD81UDZQDAZ",
        "sha256": "v",
        "ext": ".png",
        "mime": "image/png",
        "size": 122.95,
        "url": "http://localhost:1337/uploads/123456712DHZAUD81UDZQDAZ.png",
        "provider": "local",
        "provider_metadata": null,
        "created_at": "2019-12-09T00:00:00.000Z",
        "updated_at": "2019-12-09T00:00:00.000Z"
      },
      "title": "Amazing photography",
      "description": "This is an amazing photography taken..."
    }
  ],
  "opening_hours": [
    {
      "id": 1,
      "day_interval": "Mon - Sat",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    },
    {
      "id": 2,
      "day_interval": "Sun",
      "opening_hour": "7:30 PM",
      "closing_hour": "10:00 PM"
    }
  ]
}

API Parameters

WARNING

By default, the filters can only be used from find and count endpoints generated by the Content Type Builder and the CLI.

Available operators

The available operators are separated in five different categories:

Filters
Limit
Publication State

Filters

When using filters you can either pass simple filters in the root of the query parameters or pass them in a _where parameter.

Filters are used as a suffix of a field name:

Filter	Description
No suffix or `eq`	Equal
`ne`	Not equal
`lt`	Less than
`gt`	Greater than
`lte`	Less than or equal to
`gte`	Greater than or equal to
`in`	Included in an array
`nin`	Not included in an array
`contains`	Contains
`ncontains`	Doesn’t contain
`containss`	Contains, case sensitive
`ncontainss`	Doesn’t contain, case sensitive
`null`	Is null or not null

Examples

Find users having `John` as first name.

GET /users?firstName=John or GET /users?firstName_eq=John

Find restaurants having a price equal or greater than `3`.

GET /restaurants?price_gte=3

Find multiple restaurant with id 3, 6, 8.

GET /restaurants?id_in=3&id_in=6&id_in=8

Using `_where`

GET /restaurants?_where[price_gte]=3

GET /restaurants?_where[0][price_gte]=3&[0][price_lte]=7

Complex queries

NOTE

OR and AND operations are available starting from v3.1.0

When building more complex queries you must use the _where query parameter in combination with the qs (opens new window) library.

We are taking advantage of the capability of qs to parse nested objects to create more complex queries.

This will give you full power to create complex queries with logical AND and OR operations.

NOTE

We strongly recommend using qs directly to generate complex queries instead of creating them manually.

`AND` operator

The filtering implicitly supports the AND operation when specifying an array of expressions in the filtering.

Examples

Restaurants that have 1 stars and a pricing less than or equal to 20:

Restaurants that have a pricing greater than or equal to 20 and a pricing less than or equal to 50:

const query = qs.stringify({
  _where: [{ pricing_gte: 20 }, { pricing_lte: 50 }],
});
await request(`/restaurants?${query}`);
// GET /restaurants?_where[0][pricing_gte]=20&_where[1][pricing_lte]=50

`OR` operator

To use the OR operation, you will need to use the _or filter and specify an array of expressions on which to perform the operation.

Examples

Restaurants that have 1 stars OR a pricing greater than 30:

const query = qs.stringify({ _where: { _or: [{ stars: 1 }, { pricing_gt: 30 }] } });
await request(`/restaurant?${query}`);
// GET /restaurants?_where[_or][0][stars]=1&_where[_or][1][pricing_gt]=30

Restaurants that have a pricing less than 10 OR greater than 30:

const query = qs.stringify({ _where: { _or: [{ pricing_lt: 10 }, { pricing_gt: 30 }] } });
await request(`/restaurant?${query}`);
// GET /restaurants?_where[_or][0][pricing_lt]=10&_where[_or][1][pricing_gt]=30

Implicit `OR` operator

The query engine implicitly uses the OR operation when you pass an array of values in an expression.

Examples

Restaurants that have 1 or 2 stars:

GET /restaurants?stars=1&stars=2

const query = qs.stringify({ _where: { stars: [1, 2] } });
await request(`/restaurant?${query}`);
// GET /restaurants?_where[stars][0]=1&_where[stars][1]=2

NOTE

When using the in and nin filters the array is not transformed into a OR.

Combining AND and OR operators

Restaurants that have (2 stars AND a pricing less than 80) OR (1 stars AND a pricing greater than or equal to 50)

const query = qs.stringify({
  _where: {
    _or: [
      [{ stars: 2 }, { pricing_lt: 80 }], // implicit AND
      [{ stars: 1 }, { pricing_gte: 50 }], // implicit AND
    ],
  },
});
await request(`/restaurants?${query}`);
// GET /restaurants?_where[_or][0][0][stars]=2&_where[_or][0][1][pricing_lt]=80&_where[_or][1][0][stars]=1&_where[_or][1][1][pricing_gte]=50

This also works with deep filtering

Restaurants that have (2 stars AND a pricing less than 80) OR (1 stars AND serves French food)

const query = qs.stringify({
  _where: {
    _or: [
      [{ stars: 2 }, { pricing_lt: 80 }], // implicit AND
      [{ stars: 1 }, { 'categories.name': 'French' }], // implicit AND
    ],
  },
});
await request(`/restaurants?${query}`);
// GET /restaurants?_where[_or][0][0][stars]=2&_where[_or][0][1][pricing_lt]=80&_where[_or][1][0][stars]=1&_where[_or][1][1][categories.name]=French

WARNING

When creating nested queries, make sure the depth is less than 20 or the query string parsing will fail for now.

Find restaurants owned by a chef who belongs to a restaurant with star equal to 5 GET /restaurants?chef.restaurant.star=5

WARNING

Querying your API with deep filters may cause performance issues. If one of your deep filtering queries is too slow, we recommend building a custom route with an optimized version of your query.

TIP

This feature doesn’t allow you to filter nested models, e.g. Find users and only return their posts older than yesterday.

To achieve this, there are three options:

Build a custom route.
Modify your services.
Use .

WARNING

This feature isn’t available for polymorphic relations. This relation type is used in media, component and dynamic zone fields.

Sort

Sort according to a specific field.

Example

Sort users by email.

ASC: GET /users?_sort=email:ASC
DESC: GET /users?_sort=email:DESC

Sorting on multiple fields

GET /users?_sort=email:asc,dateField:desc
GET /users?_sort=email:DESC,username:ASC

Limit

Limit the size of the returned results.

The default limit is 100

Example

Limit the result length to 30.

GET /users?_limit=30

You can require the full data set by passing a limit equal to -1.

Start

Skip a specific number of entries (especially useful for pagination).

Example

Get the second page of results.

GET /users?_start=10&_limit=10

Publication State

NOTE

This parameter can only be used on models with the Draft & Publish feature activated

Only select entries matching the publication state provided.

Handled states are:

live: Return only published entries (default)

Example

Get published articles

GET /articles OR GET /articles?_publicationState=live

Get both published and draft articles

GET /articles?_publicationState=preview

NOTE

If you only want to retrieve your draft entries, you can combine the preview mode and the published_at field. GET /articles?_publicationState=preview&published_at_null=true

Content API

Content API

Restaurant Content Type

Homepage Content Type

Opening hours Component

Title With Subtitle Component

Image With Description Component

Examples

Single Types

Collection Types

Get entries

Get an entry

Count entries

Create an entry

Delete an entry

API Parameters

Available operators

Filters

Examples

Find users having John as first name.

Find restaurants having a price equal or greater than 3.

Find multiple restaurant with id 3, 6, 8.

Using _where

Complex queries

AND operator

OR operator

Implicit OR operator

Combining AND and OR operators

Sort

Example

Sort users by email.

Sorting on multiple fields

Limit

Example

Limit the result length to 30.

Start

Example

Get the second page of results.

Publication State

Example

Get published articles

Get both published and draft articles

`Restaurant` Content Type

`Homepage` Content Type

`Opening hours` Component

`Title With Subtitle` Component

`Image With Description` Component

Find users having `John` as first name.

Find restaurants having a price equal or greater than `3`.

Using `_where`

`AND` operator

`OR` operator

Implicit `OR` operator