Skip to main content
Beebole exposes a GraphQL API that gives you full programmatic access to your account data. You can read time records, people, projects, and tasks, and you can create or update records directly — all over a single HTTP endpoint. For a guided overview of what you can build with the API, see Custom Integrations.

​
Endpoint

All API requests go to: 
POST https://app.beebole.com/graphql
The API accepts application/json bodies containing a query string and an optional variables object.

​
Authentication

Beebole uses API key authentication. Include your API key as a request header named apikey: 
apikey: YOUR_API_KEY
1

Open your API key

In Beebole, click the button with your initials at the bottom of the left sidebar, then click API Key.
2

Open API settings

Go to Settings > API in your Beebole account.
3

Copy your API key

Beebole creates one API Key automatically the first time you open this panel. Click Copy to copy it to the clipboard.
4

Copy your API key

Your API Key is displayed on this page. Click Copy to copy it to the clipboard.
5

Include the key in every request

Add the apikey header to all HTTP requests you send to the endpoint.
The panel shows a single active API key, and it does not expire. The key authenticates as the person it belongs to, so requests inherit that person’s role and permissions.
Keep your API key secure. Do not 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, open the API Key panel and click Reset to revoke the current key and generate a new one.

​
Making a request

A GraphQL request is a POST with a JSON body containing a query field (and optionally variables). Here is a minimal example using curl: 
curl -X POST https://app.beebole.com/graphql \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{"query": "{ currentPerson { name email } }"}'
A successful response looks like this: 
{
  "data": {
    "currentPerson": {
      "name": "Alice Martin",
      "email": "alice@example.com"
    }
  }
}

​
Queries and mutations

The Beebole API uses standard GraphQL conventions:
  • Queries read data without side effects. Use them to fetch people, projects, tasks, time records, expense records, and more.
  • Mutations write data. Use them to create, update, archive, or delete entities.
See the full reference pages for details:
  • Queries — all available read operations
  • Mutations — all available write operations
  • Schema explorer — how to explore the schema with introspection and a GraphQL client

​
Error handling

GraphQL responses follow the standard shape: results come back under data, and any operation-level errors come back in an errors array. 
{
  "errors": [
    {
      "message": "AccountIsInactive"
    }
  ]
}

​
Authentication errors

If the apikey header is missing or invalid, Beebole cannot resolve the linked person. You may see one of these authentication messages in the errors array:
MessageCause
APIKeyError:InvalidKeyThe API key is missing or not recognized
APIKeyError:CantFindLinkedAccountThe person linked to this key no longer exists
APIKeyError:CantFindLinkedOrganisationThe organization linked to this key no longer exists

​
Permission handling

Beebole resolves permissions per operation. If a request asks for data or an action the linked person is not authorized for, Beebole omits the affected fields from data and lists their paths in a permissionsErrors array, rather than failing the whole request: 
{
  "data": {},
  "permissionsErrors": ["Query.currentPerson", "BeebolePerson.*"]
}
When an account’s subscription is inactive, API-key requests are blocked with HTTP 402 Payment Required and an AccountIsInactive error. Browser sessions are not blocked the same way, so this only affects API access.

​
Rate limits

Beebole does not apply a general rate limit to GraphQL API traffic. Rate limiting is reserved for a small set of sensitive operations — such as sign-in, sign-up, inviting people, and loading public holidays — which are not part of a typical integration workflow. For very high request volumes, batch related operations into fewer requests where possible, and contact support@beebole.com if you have specific throughput needs.

​
Related content

Queries

All available GraphQL read operations in the Beebole API.

Mutations

All available GraphQL write operations in the Beebole API.

Custom Integrations

Build custom workflows and integrations using the API.

​
Frequently asked questions

Yes. The API is standard GraphQL over HTTPS. Any language with an HTTP client — Python, JavaScript, Ruby, Go, Java, and others — can make requests.
In Beebole, click the button with your initials at the bottom of the left sidebar, then click API Key. Beebole creates the key automatically, and you can Copy or Reset it from that panel.
Yes. The API supports both queries (reading time records) and mutations (creating and editing time entries). See Queries and Mutations for the full list of operations.
The Beebole API supports GraphQL introspection, so any standard GraphQL client can fetch the full schema — types, queries, mutations, and their arguments. See the Schema explorer page for how to connect a GraphQL client.