diff --git a/api-specs/test/api.raml b/api-specs/test/api.raml
index 77566c1ffe..bdbd4f5203 100644
--- a/api-specs/test/api.raml
+++ b/api-specs/test/api.raml
@@ -515,27 +515,10 @@ traits:
           - action-errorable
           - right-header
           - frontastic-locale
-        description: Use the GET method to allow the frontend to fetch data from a backend system. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart.
+        description: Use the GET method to allow the frontend to fetch data from a backend system. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains information about a cart.
         responses:
           200:
-            description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart.
-            body:
-              application/json:
-                type: object
-                example: !include examples/action-success.json
-      post:
-        is:
-          - action-errorable
-          - right-header
-          - frontastic-locale
-        description: Use the POST method to write data to a backend system. Any JSON serializable payload is accepted. The following request example adds a product to a cart. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product.
-        body:
-          application/json:
-            type: any
-            example: !include examples/action-payload.json
-        responses:
-          200:
-            description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart.
+            description: The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart.
             body:
               application/json:
                 type: object
@@ -545,17 +528,17 @@ traits:
           - action-errorable
           - right-header
           - frontastic-locale
-        description: Use the PUT method to write data to a backend system. Any JSON serializable payload is accepted. The following request example adds a product to a cart. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product.
+        description: Use the PUT method to write data to a backend system. Any JSON serializable payload is accepted. The following request example adds a product to a cart. For the response, we recommend to use standard HTTP codes and `application/json` encoded content. The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). The following response example contains the updated cart information, which includes the added product.
         body:
           application/json:
             type: any
             example: !include examples/action-payload.json
         responses:
           200:
-            description: The response will be structured [as defined by the `body` property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart.
+            description: The response will be structured [as defined by the body property of the action](/../frontend-development/developing-an-action-extension#1-implement-the-action). We recommend to use standard HTTP response codes and `application/json` encoded content. The following response example contains information about a cart.
             body:
               application/json:
-                type: any
+                type: object
                 example: !include examples/action-success.json
 
 
diff --git a/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js b/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js
index 5287cae230..691aecbe4a 100644
--- a/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js
+++ b/packages/gatsby-theme-api-docs/src/components/resource/method/responses.js
@@ -52,7 +52,7 @@ const Responses = ({ apiKey, responses, contentType }) => {
                       typeLocations,
                       response.description
                     )}
-                    {contentType.length > 0 && (
+                    {contentType.length > 0 && !response.description && (
                       <>
                         <span>as</span>
                         <ContentType>{contentType}</ContentType>
diff --git a/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js b/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js
index 24156b4ec7..b046f1cc56 100644
--- a/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js
+++ b/packages/gatsby-theme-api-docs/src/hooks/use-api-resources.js
@@ -25,6 +25,14 @@ export const useApiResources = () => {
             type
           }
         }
+        headers {
+          header
+          builtinType
+          description
+          type
+          required
+          pattern
+        }
         responses {
           code
           description
diff --git a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js
index 28677c9d82..fcfd0b6fc0 100644
--- a/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js
+++ b/packages/gatsby-transformer-raml/src/schema/define-raml-resource.js
@@ -7,6 +7,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
       description: String
       queryParameters: [RamlResourceQueryParameter!]
       responses: [RamlResourceResponse!]
+      headers: [RamlResourceHeaders!]
       codeExamples: [RamlResourceCodeExample!]
     }
     `,
@@ -51,6 +52,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
         queryParameters: '[RamlResourceQueryParameter!]',
         body: 'RamlResourceMethodBody',
         responses: '[RamlResourceResponse!]',
+        headers: '[RamlResourceHeaders!]',
         codeExamples: '[RamlResourceCodeExample!]',
       },
       interfaces: ['Method'],
@@ -64,6 +66,7 @@ const defineRamlResource = ({ schema, createTypes }) => {
         description: 'String',
         queryParameters: '[RamlResourceQueryParameter!]',
         responses: '[RamlResourceResponse!]',
+        headers: '[RamlResourceHeaders!]',
         codeExamples: '[RamlResourceCodeExample!]',
       },
       interfaces: ['Method'],
@@ -113,6 +116,18 @@ const defineRamlResource = ({ schema, createTypes }) => {
       },
     }),
 
+    schema.buildObjectType({
+      name: 'RamlResourceHeaders',
+      fields: {
+        header: 'String!',
+        pattern: 'String',
+        type: 'String',
+        builtinType: 'String',
+        description: 'String',
+        required: 'Boolean',
+      },
+    }),
+
     schema.buildObjectType({
       name: 'RamlResourceMethodBody',
       fields: {
diff --git a/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js
new file mode 100644
index 0000000000..24cefa6433
--- /dev/null
+++ b/packages/gatsby-transformer-raml/src/utils/resource/headers-to-array.js
@@ -0,0 +1,11 @@
+function headersToArray(headers) {
+  if (headers) {
+    return Object.entries(headers).map(([key, value]) => {
+      return { header: key, ...value };
+    });
+  }
+
+  return undefined;
+}
+
+module.exports = headersToArray;
diff --git a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js
index a44b05b756..1cc7f3a1d9 100644
--- a/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js
+++ b/packages/gatsby-transformer-raml/src/utils/resource/process-methods.js
@@ -1,5 +1,6 @@
 const parametersToArray = require('../parameters-to-array');
 const responsesToArray = require('./responses-to-array');
+const headersToArray = require('./headers-to-array');
 const codeExamplesToArray = require('./code-examples-to-array');
 const examplesToArray = require('./examples-to-array').examplesToArray;
 const resolveExampleFile = require('./examples-to-array').resolveExampleFile;
@@ -33,6 +34,10 @@ function processMethods({
         returnedMethods[method].responses
       );
 
+      returnedMethods[method].headers = headersToArray(
+        returnedMethods[method].headers
+      );
+
       returnedMethods[method].codeExamples = codeExamplesToArray(
         returnedMethods[method].codeExamples
       );