Core API Introduction

The Core API can be used to manage all data in Plain. It's a public GraphQL API that powers the Support App, therefore allowing you to write code for anything that you can do in the UI.

Making API calls

Before you start making any API calls, you'll either need to:

• create an API token, see the authentication page for details on how to do that.
• use Plain's API explorer and use your logged-in user's credentials. In this case you don't need to set any custom headers and the API explorer takes care of setting the right headers. See using the API explorer section for more details.

For integrating with the GraphQL API, the technical parameters are:

• API URL: POST https://core-api.uk.plain.com/graphql/v1
• Required headers:
  • Content-Type: application/json
  • Authorization: Bearer <token> a bearer token, see authentication for details on how to obtain one.
• JSON body:
  • query: the GraphQL query string
  • variables: a JSON object of variables used in the GraphQL query
  • operationName: the name of your GraphQL operation

If you'd like to use the GraphQL schema to generate types for your client code you can fetch the schema from: https://core-api.uk.plain.com/graphql/v1/schema.graphql

Your first API call

We'll start off with an example of fetching the details of your workspace.

You can find your workspace ID in the browser's URL bar when you open the Support App and navigate to a workspace. The ID is recognizable as it starts with w_. For example in https://app.plain.com/workspace/w_123/ the workspace ID is w_123.

Save this ID as we'll need it as an input.

Using API explorer

You can access the API explorer here.

Step 1:

If you'd like to use your logged-in user's credentials, then you can select a workspace from the dropdown and skip this step. Just make sure to select the same workspace that you saved the ID for.

After having created an API key, we'll need to first set the Authorization in Request Headers:

{
  "Authorization": "Bearer plainApiKey_REPLACE_ME"
}

Step 2:

Copy the following query and variables into the API explorer:

GraphQL query:

query getWorkspace($workspaceId: ID!) {
    workspace(workspaceId: $workspaceId) {
        id
        name
        publicName
    }
}

Variables:

{
  "workspaceId": "w_01G8E2N0FK2Y5HRXQMA094ET0Z"
}

Screenshot:

Step 3:

Finally, press the run button, and you should see the details of your workspace:

🎉 Congratulations! You've just made your first API call. Now go explore the API docs for all the other things you can do.

Using curl

You'll need to set two shell variables:

• PLAIN_TOKEN: see authentication for details on how to obtain an API key
• PLAIN_WORKSPACE_ID: the ID of the workspace

PLAIN_TOKEN= # <put your API token here>
PLAIN_WORKSPACE_ID= # <put your workspace id here>
curl -X POST https://core-api.uk.plain.com/graphql/v1 \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $PLAIN_TOKEN" \
   -d '{"query":"query getWorkspace($workspaceId: ID!) { workspace(workspaceId: $workspaceId) { id name publicName } }","variables":{"workspaceId":"'"$PLAIN_WORKSPACE_ID"'"},"operationName":"getWorkspace"}'

You should see something like this as a result:

{
  "data": {
    "workspace": {
      "id": "w_01G8E2N0FK2Y5HRXQMA094ET0Z",
      "name": "Demo Inc.",
      "publicName": "Demo Inc."
    }
  }
}

Using httpie

You'll need to set two shell variables:

• PLAIN_TOKEN: see Authentication for details on how to obtain an API key
• PLAIN_WORKSPACE_ID: the ID of the workspace

PLAIN_TOKEN= # <put your token here>
PLAIN_WORKSPACE_ID= # <put your workspace id here>
http POST https://core-api.uk.plain.com/graphql/v1 \
  "Authorization:Bearer $PLAIN_TOKEN" \
  query='query getWorkspace($workspaceId: ID!) { workspace(workspaceId: $workspaceId) { id name publicName } }' \
  "variables[workspaceId]=$PLAIN_WORKSPACE_ID" \
  operationName=getWorkspace

You should see something like this as a result:

{
  "data": {
    "workspace": {
      "id": "w_01G8E2N0FK2Y5HRXQMA094ET0Z",
      "name": "Demo Inc.",
      "publicName": "Demo Inc."
    }
  }
}

---

If you have any problems, please get in touch with us by email on help@plain.com, and we will be happy to help.