The Keypup GraphQL API allows you to perform all actions accessible via the user interface, which includes adding team members, creating insights & dashboards, querying our datasets, etc.
The API is currently in closed beta and only accessible to customers. Access is enabled on a per-user basis. If you wish to access the API, please contact us via chat with your use case and we will enable your access.
The Keypup API is split into two different purpose-specific endpoints:
The Platform API (https://hq.keypup.io/graphql): This endpoint is the general-purpose API used to manage dashboards, insights, projects, and users.
The Reporting API (https://viz.keypup.io/graphql): This endpoint is the actual reporting engine used by insights to query the datasets.
1 - Authentication
1.1 - Generating API tokens
You can generate an API token by going to Settings > Account and accessing the API Token tab. Note that this tab is only accessible if API access has been enabled on your account.
Click on Create token to get started.
We strongly recommend setting a descriptive name and an expiration for your token. Permanent tokens are available as well but must be used with caution and properly secured on your side.
Once generated tokens are available to be copy/pasted for 1 minute. After this delay, only a hint is provided.
Are you going to support scopes for tokens?
Yes, this is part of our medium-term roadmap.
Are you going to support refreshable OAuth2 tokens?
Yes, as part of our medium-term roadmap. OAuth2 tokens will be the recommended authentication mechanism once released. Standard tokens will still be available as well.
1.2 - Using API tokens for authentication
The Keypup API uses Bearer authentication via the Authorization header. Simply set the Authorization header as such:
Header | Value |
|
|
The API authentication provides the same level of access as what you have on our user interface.
2 - Using the API
2.1 - Using the API Explorer
Our API explorer allows you to get started with both APIs. No tokens are required to use the Explorer since you are authenticated through your Keypup account.
The API Explorer is only accessible if API access has been enabled on your account
You can switch between APIs using the top-left dropdown.
2.2 - Accessing the documentation of each API
GraphQL APIs are discoverable and self-documented. You can access the documentation of each API by clicking the book icon on the left side.
2.3 - Exporting insights as queries
After enabling API access on your account, a new "Open in API Explorer" button will appear in the Configure Table section of the insight editor.
Clicking this button will open the query used the insight in the API Explorer.
2.4 - Using queries in application code and scripts
GraphQL queries are POST requests composed of three components:
The headers (see section "Using API tokens for authentication" above)
The query, passed as a body text attribute
The query variables, passed as a body JSON attribute
Below is an example of a cURL request making a query to our Platform API to get the name of a company, for which the ID is passed as a variable. The body is formatted as a JSON object with the query and variables attributes.
curl 'https://hq.keypup.io/graphql'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer my_keypup_api_token'
--data-raw '{"query":"query($companyId: ID) { company(id: $companyId) { name } }","variables":{"companyId":"a61bdee0-edbc-4888-9459-2ae3f2704f51"}}'
You can use any HTTP library in any language to make GraphQL queries. If manually building HTTP queries looks painful to you, you may consider one of the numerous open-source GraphQL clients out there.
A non-exhaustive list is available on the GraphQL Tools & Libraries page.
Embedding queries in the browser
It is not possible to embed queries in a web page via JavaScript. Our CORS policies prevent this for security reasons. Exposing your token in a web page would also be a bad idea.
If you wish to do so then you should have an application server making backend queries to Keypup and serving HTML pages authenticated via cookie to your users.