Using the API | Keypup Help Center

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 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.

We also strongly recommend selecting the minimum level of permissions (scopes) for your token to reduce the overall risk/exposure.

Please note that the companies:read scope (or hq:all:read) is required to access company resources. Without it, only user-specific resources will be returned when applicable. See Section 3 on available scopes for more details.

Once generated, tokens are available to be copied and pasted for 1 minute. After this delay, only a hint is provided.

Are you going to support refreshable OAuth2 tokens?
Yes. OAuth2 tokens are already supported for MCP Server accesses and will soon be made available for API tokens. Standard tokens will also remain available.

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
`Authorization`	`Bearer <my_keypup_token>`

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.

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 by 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.

3 - Available Scopes

Read and write scopes are available for each resource. They control the access that your API tokens have to the API and allow you to minimize risk exposure.

Some resources are specific to users, some specific to companies, and some to both.

If you intend to access company resources, your token must have the companies:read scope (or hq:all:read) on top of the resource-specific scope. Without the companies:read scope only resources belonging to the API token user will be returned.

Selecting a Write scope automatically grants the matching Read scope (you cannot have write without read).

Selecting hq:all:read or hq:all:write is a wildcard that covers every HQ entity, including any future entities added to the API.

3.1 Viz Scopes (Reporting API)

Entity	Scopes	Description
Reports	`viz:reports:read`	Execute queries against the Viz reporting engine. Supports metrics, dimensions, filters, and pagination across all datasets.

3.2 HQ Scopes (Platform API)

Entity	Scopes	Description
All resources	`hq:all:read` `hq:all:write`	Wildcard scope granting access to all HQ platform resources, including any future resources added to the API.
Accounts	`hq:accounts:read`	Third-party organisations or workspaces discovered via integrations (e.g., a GitHub org, a Jira Cloud site). Relationship: Integration > Accounts > Projects.
API tokens	`hq:api_tokens:read`	Personal API tokens created by the user for programmatic access. Includes token metadata (description, expiration, scopes).
Apps	`hq:apps:read`	Integration app catalog (GitHub, GitLab, Jira, Bitbucket, Azure DevOps, etc.). Each app has a provider, category, and stage.
Agent discussions	`hq:agent_discussions:read`	AI Agent conversation threads. Each discussion has a category (widget or dashboard) and contains a sequence of prompt/response parts.
Billing invoices	`hq:billing_invoices:read`	Stripe invoices associated with the company subscription (amount, status, dates).
Billing subscriptions	`hq:billing_subscriptions:read`	Company subscription plan and billing status managed via Stripe.
Companies	`hq:companies:read` `hq:companies:write`	Team workspaces. Write access allows updating company name and AI steering configuration.
Company invites	`hq:company_invites:read` `hq:company_invites:write`	Pending email invitations to join a team workspace (email, role, expiration).
Dashboards	`hq:dashboards:read` `hq:dashboards:write`	Dashboard resources including layout, filters, icon, description, and associated widgets.
Identities	`hq:identities:read`	User identities across connected platforms - maps a user to their login username and provider (e.g., GitHub username, Jira account).
Import batches	`hq:import_batches:read`	Data import operations triggered when syncing projects. Tracks progress and status of each batch.
Integrations	`hq:integrations:read`	Active connections between an app (e.g., GitHub) and the company. Each integration has a status and links to an app provider.
Pins	`hq:pins:read` `hq:pins:write`	Pinned dashboards and their assignment to pin groups in the sidebar navigation.
Pin groups	`hq:pin_groups:read` `hq:pin_groups:write`	Named collections used to organize pinned dashboards in the sidebar (name, icon, ordering).
Projects	`hq:projects:read`	Projects imported from connected integrations (repositories, Jira boards, Azure DevOps projects, etc.).
Roles	`hq:roles:read` `hq:roles:write`	Resource-level access control roles (owner, editor, viewer) assigned to users or the company on dashboards and widgets.
Users	`hq:users:read` `hq:users:write`	User accounts (first name, email, profile). Write access allows updating user profile and unenrollment.
User company relations	`hq:user_company_rels:read` `hq:user_company_rels:write`	Memberships linking users to companies. Each membership has a role (admin, member), status, and optional expiration.
User sessions	`hq:user_sessions:read`	Active authentication sessions for the current user (read-only).
Widgets	`hq:widgets:read` `hq:widgets:write`	Individual insight widgets (charts, KPIs, tables, cards). Write access allows creating, updating, and deleting widgets.