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

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)

# Endpoints

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

# Examples

Here are some Content Type examples

# Single Types
# Collection Types

# Get entries

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

# Get an entry

Returns an entry by id.

# Count entries

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

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

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

# Delete an entry

Deletes an entry by id and returns its value.

# API Parameters

WARNING

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

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:

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:

GET /restaurants?stars=1&stars=2

or

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.

# Deep filtering

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.

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

# 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

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

← React →