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 stringvariables
: a JSON object of variables used in the GraphQL queryoperationName
: 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 keyPLAIN_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 keyPLAIN_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.