> ## Documentation Index
> Fetch the complete documentation index at: https://beebole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Documentation

> Get started with the Beebole GraphQL API: how the endpoint works, how to authenticate with an API key, and how to send your first query or mutation.

Beebole exposes a [GraphQL](https://graphql.org/) 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](/help/integrations/custom-integrations).

***

## Endpoint

All API requests go to:

```text theme={null}
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`:

```http theme={null}
apikey: YOUR_API_KEY
```

<Steps>
  <Step title="Open your API key">
    In Beebole, click the button with your initials at the bottom of the left sidebar, then click **API Key**.
  </Step>

  <Step title="Open API settings">
    Go to **Settings** > **API** in your Beebole account.
  </Step>

  <Step title="Copy your API key">
    Your **API Key** is displayed on this page. Click **Copy** to copy it to the clipboard.
  </Step>

  <Step title="Include the key in every request">
    Add the `apikey` header to all HTTP requests you send to the endpoint.
  </Step>
</Steps>

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.

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

***

## 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`:

```bash theme={null}
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:

```json theme={null}
{
  "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](/help/api/queries) — all available read operations
* [Mutations](/help/api/mutations) — all available write operations
* [Schema explorer](/help/api/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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](mailto:support@beebole.com) if you have specific throughput needs.

***

## Related content

<CardGroup cols={2}>
  <Card title="Queries" icon="magnifying-glass" href="/help/api/queries">
    All available GraphQL read operations in the Beebole API.
  </Card>

  <Card title="Mutations" icon="pen" href="/help/api/mutations">
    All available GraphQL write operations in the Beebole API.
  </Card>

  <Card title="MCP server" icon="plug" href="/help/integrations/mcp-server">
    Let Claude, ChatGPT, or Claude Code work with your Beebole data.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/help/integrations/webhooks">
    Receive signed, real-time event notifications on your own endpoints.
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/help/api/queries) and [Mutations](/help/api/mutations) for the full list of operations.
  </Accordion>

  <Accordion title="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](/help/api/schema-explorer) page for how to connect a GraphQL client.
  </Accordion>
</AccordionGroup>