Skip to main content
Beebole’s GraphQL API lets you build custom integrations that connect Beebole to any tool or internal system your organization uses. When the built-in integrations don’t cover your needs, the API gives you full programmatic access to read and write your Beebole account data. This page is a starting point. For endpoints, authentication details, queries, and mutations, see the API introduction.

​
What you can build

Beebole’s GraphQL API supports both queries (reading data) and mutations (creating or updating data). Common custom integrations include:

​
Get your API key

Each person in Beebole has one personal API key that authenticates their API requests, and it does not expire. You create it yourself: opening Your API key does not create one. The key acts with your own role and permissions, so an integration can read and change only what you can.
1

Open Your API key

Click the button with your initials at the bottom of the sidebar, then hover over or click Your API key.
2

Create the key

Click Create an API key.
3

Copy the key within 30 seconds

The full key appears with the message You have 30 seconds to copy the key. Click Copy and store the key in an environment variable or a secrets manager.
Beebole user menu with Your API key highlighted and its submenu showing only the first and last four characters of the key, with the Reset button

Your API key, in the menu of the initials button

4

Authenticate your requests

Include the key in your API requests as described in the API introduction.
Beebole shows the full key only once, right after you create or reset it, with 30 seconds to copy it. After that, only its first and last four characters show. Your API key is the same one you use in every tool you connect, so if you already use it elsewhere, paste that copy. If you no longer have it, click Reset under Your API key to get a new one: the old key stops working at once, in every tool that used it.
Keep your API key secure. Don’t include it in client-side code or commit it to public repositories — store it in an environment variable or a secrets manager. If a key is compromised, click Reset right away: the old key stops working at once, and Beebole shows the new one in full for 30 seconds.

​
Build your integration

1

Read the API documentation

Start with the API introduction and the API pages that follow it. They cover authentication, the schema explorer, queries, and mutations.
2

Explore the schema

Use the schema explorer to browse all available types, queries, and mutations. This helps you understand the data model before writing your integration.
3

Build and test your integration

Start with simple queries to read data, then move to mutations when you are ready to create or update records. Every mutation changes your live Beebole data, so try it on a few records before you run it on all of them.

​
Best practices

Start with a read-only integration (queries only) to validate your data mapping before writing data back to Beebole.
  • Give the projects and people your integration creates clear names, so they are easy to recognize in Beebole.
  • Check both the errors array and the permissionsErrors array in every response. When a request asks for data or an action your role doesn’t allow, Beebole leaves those fields out and lists them in permissionsErrors instead of failing the whole request.

​
Related content

API introduction

Authenticate with the Beebole GraphQL API and send your first request.

Webhooks

Send real-time Beebole event notifications to your own services.

All integrations

Browse the built-in Beebole integrations.

​
Frequently asked questions

Click the button with your initials at the bottom of the sidebar and hover over Your API key. If you don’t have a key yet, click Create an API key. Beebole shows the full key only once, right after you create or reset it, with 30 seconds to copy it. After that, only its first and last four characters show, so if you no longer have the key, click Reset to get a new one. Each person has one key, and it does not expire.
Any language with an HTTP client. The Beebole API uses standard GraphQL over HTTPS, so Python, JavaScript, Ruby, Go, Java, and others all work.
Yes. The Beebole API supports mutations for creating and updating time entries, projects, people, and other records. See the API introduction for details.
In Beebole, Reset replaces your current key with a new one at once, with no confirmation. The old key stops working right away, and every integration or tool using it stops until you update it with the new key. Beebole shows the new key in full for 30 seconds only, so copy it right away. Reset when a key is compromised or when you no longer have a copy of it.
The same data you can access in Beebole. Your API key acts with your own role and permissions, so an integration can read and change only what you can. Fields your role doesn’t cover are left out of the response and listed in permissionsErrors.