Beebole GraphQL API: Endpoint, Authentication, First Request

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.

This API belongs to the new Beebole platform at app.beebole.com. If you sign in at beebole-apps.com, you are on the Legacy platform: its API token is not accepted by /graphql, and the Legacy API documentation applies instead. Not sure which one you use? See Which Beebole am I using?.

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

Open your API key

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

Copy your API key

Your key is displayed, partly masked. Click Copy to copy the full key to the clipboard.

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 Your API key again 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:

Message	Cause
`APIKeyError:InvalidKey`	The API key is missing or not recognized
`APIKeyError:CantFindLinkedAccount`	The person linked to this key no longer exists
`APIKeyError:CantFindLinkedOrganisation`	The 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.

Troubleshooting

Empty `data` and `permissionsErrors` on every field

An invalid or revoked key does not fail the request outright. Beebole runs the query with no permissions at all, so data comes back empty, permissionsErrors lists every path you asked for, and the errors array names the real cause — APIKeyError:InvalidKey or one of the other authentication messages above. Read errors first: an APIKeyError there means the key is the problem, not the linked person’s role. A permissionsErrors array without an APIKeyError means the key works and the role does not cover those fields.

Send the key exactly as shown

The apikey header takes the key as Beebole displays it. Don’t base64-encode it and don’t wrap it in HTTP basic authentication the way the Legacy API required — an encoded key is not recognized and returns APIKeyError:InvalidKey. The Authorization: Bearer header is reserved for the tokens of the MCP server.

The key comes from a Legacy account

Tokens issued by the Legacy platform (beebole-apps.com) are not recognized by https://app.beebole.com/graphql and return APIKeyError:InvalidKey with an empty data. A Legacy account keeps using the Legacy API; the GraphQL API becomes available once the account is migrated to the new platform.

`402 Payment Required` with `AccountIsInactive`

The account’s subscription is canceled or its trial has expired, and API keys have no way to reactivate it. An administrator restores access by renewing the subscription from the browser. The Free plan is not affected — see the FAQ below.

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.

Queries

All available GraphQL read operations in the Beebole API.

Mutations

All available GraphQL write operations in the Beebole API.

MCP server

Let Claude, ChatGPT, or Claude Code work with your Beebole data.

Webhooks

Receive signed, real-time event notifications on your own endpoints.

Frequently asked questions

Can I use any programming language with the API?

Yes. The API is standard GraphQL over HTTPS. Any language with an HTTP client — Python, JavaScript, Ruby, Go, Java, and others — can make requests.

Where do I find my API key?

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.

Can I use the API to read and write time records?

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.

How do I explore the API schema?

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.

Does the API work on the Free plan?

Yes. Beebole does not gate API access by plan: an API key from a Free account works like any other, with the permissions of the person it belongs to. The only subscriptions blocked from the API are canceled ones and expired trials, which answer 402 Payment Required with AccountIsInactive. Fields that belong to features outside your plan — billing rates on the Free plan, for example — come back in permissionsErrors rather than in data.

How do I find timesheets that are still drafts or awaiting approval?

Not by filtering time records — a time record carries no approval status, because the status belongs to the timesheet period. Use getPendingApprovals for every submission waiting for approval, and getApprovalState or getTeamApprovalStates to read a period’s status (d draft, s submitted, a approved, r rejected). See Timesheets and approvals on the Queries page.

GraphQL API

Examples

MCP & Webhooks

Legacy

API Documentation

Endpoint

Authentication

Making a request

Queries and mutations

Error handling

Authentication errors

Permission handling

Troubleshooting

Empty `data` and `permissionsErrors` on every field

Send the key exactly as shown

The key comes from a Legacy account

`402 Payment Required` with `AccountIsInactive`

Rate limits

Queries

Mutations

MCP server

Webhooks

Frequently asked questions

​Endpoint

​Authentication

​Making a request

​Queries and mutations

​Error handling

​Authentication errors

​Permission handling

​Troubleshooting

​Empty data and permissionsErrors on every field

​Send the key exactly as shown

​The key comes from a Legacy account

​402 Payment Required with AccountIsInactive

​Rate limits

​Related content

Queries

Mutations

MCP server

Webhooks

​Frequently asked questions

Endpoint

Authentication

Making a request

Queries and mutations

Error handling

Authentication errors

Permission handling

Troubleshooting

Empty `data` and `permissionsErrors` on every field

Send the key exactly as shown

The key comes from a Legacy account

`402 Payment Required` with `AccountIsInactive`

Rate limits

Related content

Frequently asked questions