Requests & Responses

💬 Strapi team needs you to improve this documentation!

We are currently reworking the Backend Customization section of the Strapi documentation. If you would like to help, please feel free to fill in this form to share with us your opinions, needs and requests.

Requests

When you send requests through the REST API, the context object (ctx) contains all the requests related information. They are accessible through ctx.request, from controllers and policies.

Strapi passes the body on ctx.request.body, query on ctx.request.query, params on ctx.request.params and files through ctx.request.files

For more information, please refer to the Koa request documentation and Koa Router documentation.

Responses

The context object (ctx) contains a list of values and functions useful to manage server responses. They are accessible through ctx.response, from controllers and policies.

For more information, please refer to the Koa response documentation.

CTX Table

ctx

Parameter	Description	Type
ctx	Ctx is the context object that is given to every layer within strapi	Object

ctx.request

Parameter	Description	Type
ctx.request	The request you got from the client that did an api request.	Object
ctx.request.body	Parsed version of the body	Object
ctx.request.params	The params send in the url. Example /${info.pluralName}/:id then the :id part would create a param named id. To get the example parm you would do ctx.request.params.id.	Object
ctx.request.files	the files send with the request.	Array
ctx.request.headers	All headers send with the request.	Object
ctx.request.url	Gives you back the url from the first /.	String
ctx.request.origin	Gives you back the url without the / and everything behind it.	String
ctx.request.href	Gives you back the full url excluding the params.	String
ctx.request.method	Gives you back the method examples of methods are GET or POST.	String
ctx.request.path	Gives you back the full url.	String
ctx.request.host	Only gives the host part of the url.	String
ctx.request.host	Only gives the host part of the url without the port	String
ctx.request.host	Protocol being used examples: https or http.	String
ctx.request.ips	When X-Forwarded-For is present and app.proxy is enabled an array of these ips is returned, ordered from upstream -> downstream. For example if the value were "client, proxy1, proxy2", you would receive the array ["client", "proxy1", "proxy2"].	Array
ctx.request.ip	IP of the person who send the request.	String
ctx.request.subdomains	For example, if the domain is "tobi.ferrets.example.com": it is ["ferrets", "tobi"].	Array

ctx.request.query

Parameter	Description	Type
ctx.request.query ctx.query	API parameters can be used with the REST API to filter, sort, and paginate results and to select fields and relations to populate	Object
ctx.request.query.sort	Sort the response	String Array
ctx.request.query.filters	Filter the response	Object
ctx.request.query.populate	Populate relations, components, or dynamic zones	String Object
ctx.request.query.fields	Select only specific fields to display	Array
ctx.request.query.pagination	Page through entries	Object
ctx.request.query.publicationState	Select the Draft & Publish state Only accepts the following values: live(default) preview	String
ctx.request.query.locale	Select one or multiple locales	String Array

ctx.response

Parameter	Description	Type
ctx.response	The response the server will give back	Object
ctx.response.body	The body of the response	Any
ctx.response.status	the status code of the response	Integer
ctx.response.message	Get response status message. By default, response.message is associated with response.status.	String
ctx.response.header ctx.response.headers	The headers of the response	Object
ctx.response.length	Return response Content-Length as a number when present, or deduce from ctx.body when possible, or undefined.	Integer
ctx.response.redirect	ctx.response.redirect(url, [alt]) Perform a [302] redirect to url. The string "back" is special-cased to provide Referrer support, when Referrer is not present alt or "/" is used. Example: ctx.response.redirect('back', '/index.html');	Function
ctx.response.attachment	ctx.response.attachment([filename], [options])
Set Content-Disposition to "attachment" to signal the client to prompt for download. Optionally specify the filename of the download and some options.	Function
ctx.response.type	Get response Content-Type void of parameters such as "charset".	String
ctx.response.lastModified	Return the Last-Modified header as a Date, if it exists.	DateTime
ctx.response.etag	Set the ETag of a response including the wrapped "s. Note that there is no corresponding response.etag getter.	String

ctx.state

Parameter	Description	Type
ctx.state	the strapi state of the request	Object
ctx.state.isAuthenticated	Tells you if the current user is authenticated in any way	Boolean

ctx.state.user

Parameter	Description	Type
ctx.state.user	Normal user object where all fields are there but only role relation is populated	Object
ctx.state.user.role	The users role	Object

ctx.state.auth

Parameter	Description	Type
ctx.state.auth	the auth object	Object
ctx.state.auth.strategy	the object of the currently used strategy	Object
ctx.state.auth.strategy.name	the name of the currently used strategy	String

ctx.state.route

Parameter	Description	Type
ctx.state.route	the object with all the information of the current route	Object
ctx.state.route.method	method of the current route	String
ctx.state.route.path	path of the current route	String
ctx.state.route.config	All configuration of the route	Object

ctx.state.info

Parameter	Description	Type
ctx.state.info	The info object	Object
ctx.state.info.apiName	The name of the used api	String
ctx.state.info.type	the type of the used api	String

Accessing the request context anywhere

✨ New in v4.3.9

The strapi.requestContext works with Strapi v4.3.9+.

Strapi exposes a way to access the current request context from anywhere in the code (e.g. lifecycle functions).

You can access the request as follows:

const ctx = strapi.requestContext.get();

You should only use this inside of functions that will be called in the context of an HTTP request.

// correct

const service = {
  myFunction() {
    const ctx = strapi.requestContext.get();
    console.log(ctx.state.user);
  },
};

// incorrect
const ctx = strapi.requestContext.get();

const service = {
  myFunction() {
    console.log(ctx.state.user);
  },
};

Example:

./api/test/content-types/article/lifecycles.js

module.exports = {
  beforeUpdate() {
    const ctx = strapi.requestContext.get();

    console.log('User info in service: ', ctx.state.user);
  },
};

✏️ Note

Strapi uses a Node.js feature called AsyncLocalStorage to make the context available anywhere.