Skip to main content

Make your first call

Make your first call to the Studio API: list the projects you can reach. You need this before the other pages in this topic, because every call takes the same credential and organization UID.

The example is the Blog project in the AWS NA region.

Prerequisites​

  • A credential. An OAuth access token or a session token for a user who can read the project's stack. The curl commands in this topic read an OAuth access token from CS_ACCESS_TOKEN.
  • Your organization's UID. The UID of the organization that owns your projects. The example's is blt2222222222222222.
  • The base URL for your region. The example uses AWS NA, https://composable-studio-api.contentstack.com/v1. Every path starts with /v1. For the other regions, see Base URL for each region.
  • Access to the project's stack. You need read access for reads, and write access to create, change or delete.

What this is and what you get​

You send two headers on every call: your credential and organization_uid. After this page, you can call the API from your own shell, and you know how it answers when something is wrong.

The API acts as you. It passes your own token on to Contentstack instead of using a credential of its own, so it can do what your token can do.

Choose a credential​

You send either authtoken with a session token, or authorization: Bearer <access_token> with an OAuth access token. Both work. The API passes exactly one credential on to Contentstack, never both.

HeaderValueRequired
authtokenYour Contentstack session token.One of authtoken or authorization
authorizationBearer <access_token>, an OAuth access token. The Bearer prefix is required.One of authtoken or authorization
organization_uidThe UID of the organization that owns the project.Yes, on every call
Content-Typeapplication/jsonOn POST and PUT only
  • The API ignores an authorization value that doesn't start with Bearer, such as a bare management token.
  • If you send both credentials, the API passes on the OAuth token when Contentstack identifies you as an OAuth app, and the session token otherwise.
  • Composition routes and the registered components route pass your credential on. Project routes never read it.
  • A composition call with no usable credential answers 401 with error code 39. The registered components route answers 401 with error code 48. The API checks this after it finds the project and checks your stack access, so another error can come first.
  • A token without access to the project's stack gets 422 with error code 21, not 403. Reading a project you can't see answers 404 with error code 1.

For the full header and access tables, see API endpoints.

Send your first request​

To list the projects you can reach, send GET /v1/projects.

curl "https://composable-studio-api.contentstack.com/v1/projects" \
  -H "authorization: Bearer $CS_ACCESS_TOKEN" \
  -H "organization_uid: blt2222222222222222"

The API answers 200 with { "projects": [ ... ] }. Blog is one of the items. The answer has no count, no page fields and no default limit.

The list holds live projects in your organization whose stack you can access, and live projects you created. If you can see none, the API answers 200 with { "projects": [] }, not 404.

Keep the uid of the project you want to work in. Every composition call takes it in the path. If you have no project yet, Manage projects with the API creates one.

If it doesn't work​

  • The list is empty, or a project is missing. The list holds live projects whose stack you can access, plus the ones you created. Check the organization_uid header and your access to the stack.
  • 401 with error code 39 or 48. On a composition or registered components call, neither an authtoken nor an authorization: Bearer token reached the API.
  • 422 with error code 21 and Stack not found. Your token has no access to the project's connected stack. A read needs read access, and anything else needs write access.
  • 408. The call ran past 60 seconds. The body is { "message": "Request Timeout", "statusCode": 408 }.

Where to go next:

Report a problem with this page