GraphQL API
Plain's GraphQL API can be used to manage any aspect of Plain. It's the API that we use to build the Plain app which means there are no restrictions in what you can do via the API vs the Plain app.
Key details
Our API is compatible with all common GraphQL clients with the following details:
- API URL:
https://core-api.uk.plain.com/graphql/v1
- Allowed method: POST
- Required headers:
Content-Type: application/json
Authorization: Bearer <token>
where token is your API key. See authentication for more details.
- JSON body:
query
: the GraphQL query stringvariables
: a JSON object of variables used in the GraphQL queryoperationName
: the name of your GraphQL operation (this is just for tracking and has no impact on the API call or result)
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
In this example, we're going to get a customer in your workspace by their email address. You can find a customer's email on the right-hand side when looking at them in Plain.
You will need an API key with the customer:read
permission. See authentication for details on how to get an API key
You'll need to set two shell variables:
PLAIN_TOKEN
: The API keyPLAIN_CUSTOMER_EMAIL
: The email of the customer you want to fetch
PLAIN_TOKEN=XXX
PLAIN_CUSTOMER_EMAIL=XXX
curl -X POST https://core-api.uk.plain.com/graphql/v1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PLAIN_TOKEN" \
-d '{"query":"query customerByEmail($email: String!) { customerByEmail(email: $email) { id fullName updatedAt { iso8601 } } }","variables":{"email":"'"$PLAIN_CUSTOMER_EMAIL"'"},"operationName":"customerByEmail"}'