**Source:** https://heykiku.com/help/api-getting-started

# Getting started with the REST API

The heykiku REST API is one of the ways you can [connect heykiku to your stack](https://heykiku.com/features/connect), automating the parts of your knowledge workflow that don't need a human in the loop — document uploads, folder organization, listing past conversations. Workspace administration (team, billing, settings) stays in the dashboard; API keys are scoped to read or write the knowledge surface, not to manage the workspace.

## Who can use the API

API access is included with the [Bloom plan](/pricing). Lower plans don't see API keys in their settings.

Inside a Bloom workspace, the **owner** decides who can mint keys. By default no one but the owner can issue a key. The owner grants issuance via the team page:

- **None** — can't mint keys (the default for new members)
- **Read only** — can mint keys with the `read` scope
- **Read + write** — can mint keys with either scope, but the member also needs upload, approve, or organize capability for `write` to be effective

Freelancers can be granted issuance, but only `read` keys take effect at request time.

## Create your first key

1. Go to **Settings → API keys** in the dashboard.
2. Click **New key**.
3. Pick a scope: `read` for read-only automation; `read + write` if your integration uploads documents or organizes folders.
4. Optionally set an **IP allowlist** (CIDR notation) and an **expiry date**.
5. Click **Create**. You'll see the raw key once — copy it now. We only store a hash; we can never show it again.

The key looks like `kiku_live_<48-byte-base62>`. Treat it like a password: never commit it, never paste it into chat. Anyone with the key has whatever scope you granted it.

## Make your first request

```bash
curl -H "Authorization: Bearer kiku_live_..." \
  https://heykiku.com/api/folders
```

A successful response is JSON. `GET /api/folders` returns the full accessible set in one call — there's no pagination on folders:

```json
{
  "folders": [
    {
      "id": "...",
      "name": "Onboarding",
      "accessTagId": "...",
      "color": null,
      "description": null,
      "documentCount": 12
    }
  ]
}
```

If you get a 401, your bearer header is missing or the key was revoked. If you get a 403 with `API_KEY_SCOPE_INSUFFICIENT`, the action needs `write` and your key is `read` only.

## Full endpoint reference

The [API reference](/api-reference) links to the OpenAPI spec at `/openapi.json`. Paste that URL into Claude, ChatGPT, or Cursor to generate client code, sample requests, or ask questions about any endpoint — or point a code generator at it directly.

## Related terms

- [Agency Tech Stack](https://heykiku.com/glossary/agency-tech-stack)
- [Agency Knowledge Base](https://heykiku.com/glossary/agency-knowledge-base)
- [Single Source of Truth](https://heykiku.com/glossary/single-source-of-truth)