Skip to content

Revise README for improved API usage instructions #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PriyadarshanKhadtale merged 1 commit into from
Mar 4, 2026
Merged

Revise README for improved API usage instructions #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 73 additions & 65 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,77 +1,85 @@
<img
src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/bltddc0acd6b98c881c/Contentstack-Logo" width="70" height="75">
<h1>Contentstack CDA/CMA OpenAPI</h1>
<p>Contentstack provides OpenAPI files for its Content Delivery and Content Management REST APIs. These files are in
JSON format. Using these JSON files, you can automatically generate API documentation, test API, and do a lot more.

<p>
Contentstack provides OpenAPI files for its <a href="https://www.contentstack.com/docs/developers/apis/content-delivery-api">Content Delivery</a> and <a href="https://www.contentstack.com/docs/developers/apis/content-management-api">Content Management</a> APIs in JSON format. These files allow you to automatically generate API documentation, test requests, and streamline your development workflow.
</p>
<p>
This tutorial walks you through how to use these JSON files with Swagger Editor to interact with Contentstack’s APIs.
</p>
<p>This tutorial will walk you through the process of using Contentstack APIs (Content Delivery and Content Management
APIs) with Swagger.</p><br>
<h2>Content Delivery API (CDA)</h2>
<p>Version: 3.0.0 <a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">[Download]</a></p>
<p>Last Updated: Feb 06, 2023</p>
<p><strong>Note</strong>: To use the latest version, <a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">download
the CDA file</a> on your system. </p>
<p>To use Contentstack Content Delivery API (CDA) with Swagger, perform the following steps: </p>


<p>
To use CDA with Swagger, follow these steps:
</p>
<ol>
<li><a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">Download
the CDA file</a> and go to the <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>
<li>On the “Swagger Editor” page, click on <strong>File</strong>, and select the <strong>Import file</strong> option.
</li>

<li><a href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">Download the latest CDA JSON file</a> and navigate to <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>

<li>Click <strong>File</strong> on top-right and select <strong>Import File</strong> to upload the JSON.</li>

<li>Open any API request and click the <strong>Try it out</strong> button to unlock the parameter fields.</li>

<li>Enter your stack's values or use the default demo stack credentials.</li>

<li>Click <strong>Execute</strong>.</li>
</ol>
<p>Alternatively, if you want to use the Import URL option, you can <a
href="https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/">upload the CDA
file as an asset</a> in Contentstack, and then paste the asset’s URL in the prompt.</p>
<ol>
<li>Open any API request and click on the <strong>Try it out </strong>button. Clicking this button will unlock the
fields, so you can either run the API request on our demo stack or can use your own values.</li>
<li>Click on <strong>Execute</strong>.</li>
</ol><br>
<p>In the <strong>Responses </strong>section, you can see the following details:</p>
<p>
The <strong>Responses</strong> section will display the following:
</p>
<ul>
<li>API request in CURL format</li>
<li>Response body</li>
<li>Status code </li>
</ul><br>
<h2>Content Management API</h2>
<p>Version: 3.0.0 <a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">[Download]</a></p>
<p>Last Updated: Feb 06, 2023</p>
<p><strong>Note</strong>: To use the latest version, <a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">download
the CMA file</a> on your system. </p>
<p>To use Contentstack Content Management API (CMA) with Swagger, perform the following steps: </p>

<li>The API request in cURL format.</li>

<li>The response body (JSON).</li>

<li>The HTTP status code.</li>
</ul>
<p>
<strong>Note</strong>: To ensure you are testing against the most accurate environment, always download the latest CDA file from the Contentstack documentation site.
</p>
<h2>Content Management API (CMA)</h2>


<p>
To use CDA with Swagger, follow these steps:
</p>
<ol>
<li><a
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">Download
the CMA file</a> and go to the <a href="https://editor.swagger.io/">Swagger Editor</a>. </li>
<li>On the “Swagger Editor” page, click on<strong> File</strong>, and select the <strong>Import file </strong>option.
</li>
<li>Alternatively, you can <a
href="https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/">upload the CMA
file as an asset</a> in Contentstack. Then, you can use the <strong>Import URL</strong> option and paste the
asset’s URL in the prompt. </li>
<li>To run any API request for CMA, make sure you have either the Management token or Auth token in hand. <ol>
<li>To use a management token, refer to the Generate Management token guide. </li>
<li>To use Auth token, run the <strong>Login </strong>API request, located under the <strong>User Session
</strong>section. </li>
</ol>
</li>
<li>Open any API request and click on the <strong>Try it out</strong> button. Clicking this button will unlock the
fields for you to use your enter the values. </li>
<li>Click <strong>Execute</strong>.</li>
</ol><br>
<p>In the <strong>Responses </strong>section, you can see the following details:</p>

<li><a href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">Download the latest CMA JSON file</a> and navigate to <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>

<li>Click <strong>File</strong> on top-right and select <strong>Import File</strong> to upload the JSON.</li>

<li>Before running a request, ensure you have an authentication method ready:</li>

<li><strong>Management Token</strong>: We recommend using a management token for CMA requests. Refer to the <a href="https://www.contentstack.com/docs/developers/create-tokens/generate-a-management-token">Generate Management Token</a> guide for details.</li>

<li><strong>Authtoken</strong>: Run the <a href="https://www.contentstack.com/docs/developers/apis/content-management-api#log-in-to-your-account">Log in API request</a> under the <strong>User Session</strong> section to retrieve an <code>authtoken</code> in the response.</li>

<li>Open any API request and click the <strong>Try it out</strong> button to unlock the parameter fields.</li>

<li>Enter your stack's values or use the default demo stack credentials.</li>

<li>Click <strong>Execute</strong>.</li>
</ol>
<p>
The <strong>Responses</strong> section will display the following:
</p>
<ul>
<li>API request in CURL format</li>
<li>Response body</li>
<li>Status code</li>

<li>The API request in cURL format.</li>

<li>The response body (JSON).</li>

<li>The HTTP status code.</li>
</ul>
<h2>Points to note:</h2>
<p>
<strong>Note</strong>:
</p>
<ul>
<li>We recommend using the Management token for executing CMA requests rather than Auth token. </li>
<li>For any DELETE request that has a request body in it, you won’t be able to run it in Swagger. In such scenarios,
refer to the documentation link provided in the call for more details.</li>
</ul><br>

<li>We recommend using the Management token for executing CMA requests rather than authtoken.</li>

<li>For any DELETE request that has a request body in it, you won’t be able to run it in Swagger.</li></ul>