# Content API

# API Endpoints

When you create a Content Type you will have a certain number of REST API endpoints available to interact with it.

✋ CAUTION

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)

Fields	Type	Description	Options
name	string	Restaurant's title
slug	uid	Restaurant's slug	`targetField="name"`
cover	media	Restaurant's cover image
content	dynamiczone	The restaurant profile content
opening_hours	component	Restaurant's opening hours component	`repeatable`

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

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

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

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

# Endpoints

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

Method	Path	Description
GET	`/{content-type}`	Get a list of {content-type} entries
GET	`/{content-type}/:id`	Get a specific {content-type} entry
GET	`/{content-type}/count`	Count {content-type} entries
POST	`/{content-type}`	Create a {content-type} entry
DELETE	`/{content-type}/:id`	Delete a {content-type} entry
PUT	`/{content-type}/:id`	Update a {content-type} entry

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

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

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

# Collection Types

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

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

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

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

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 here.

Example request

GET http://localhost:1337/restaurants

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,
        "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"
    }
  ]
}

# 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

1

# Create an entry

Creates an entry and returns its value.

If the Internationalization (i18n) plugin is installed, it's possible to use POST requests to the Content API to create localized entries.

Example request

POST http://localhost:1337/restaurants

{
  "title": "Restaurant 1",
  "cover": 1,
  "content": [
    {
      "__component": "content.title-with-subtitle",
      "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": [
    {
      "day_interval": "Tue - 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": 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"
    }
  ]
}

# Update an entry

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

✏️ NOTE

It's currently not possible to update the locale of an entry.

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",
        "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"
    }
  ]
}

# Delete an entry

Deletes an entry by id and returns its value.

Example request

DELETE 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": 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

✋ CAUTION

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

Queries to Strapi Content API can use several API parameters:

Filters
Sort
Limit
Start
Publication State
Locale

# 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.

Example requests: 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`

Example request: Find restaurants having a price equal or greater than `3`

GET /restaurants?price_gte=3

# Find multiple restaurant with id 3, 6, 8

Example request: Find multiple restaurant with id 3, 6, 8

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

# Using `_where`

Example requests: Using the _where filter

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.

✋ CAUTION

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:

const query = qs.stringify({
  _where: [{ stars: 1 }, { pricing_lte: 20 }],
});

await request(`/restaurants?${query}`);
// GET /restaurants?_where[0][stars]=1&_where[1][pricing_lte]=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:

Example request: 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

✋ CAUTION

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

# Deep filtering

Example request: 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 GraphQL.

✋ CAUTION

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.

# Examples

Example requests: Sort users by email

GET /users?_sort=email:ASC to sort by ascending order

GET /users?_sort=email:DESC to sort by descending order

Example requests: 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.

Example request: 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

Example request: 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)
preview: Return both draft entries & published entries

# Example

# Get published articles

Example requests: Get published articles

GET /articles

GET /articles?_publicationState=live

# Get both published and draft articles

Example request: 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

# Locale

If the Internationalization (i18n) plugin is installed and localization is enabled for the content-type, the locale API parameter can be used to get entries from a specific locale.

← Migration React →

# Content API

# API Endpoints

# Endpoints

# Examples

# Single Types

# Collection Types

# Get entries

# Get an entry

# Count entries

# Create an entry

# Update an entry

# Delete an entry

# API Parameters

# 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

# Deep filtering

# Sort

# Examples

# 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

# Locale

# 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