**Source:** https://heykiku.com/help/api-common-workflows

# Common API workflows

These workflows cover the high-frequency endpoints. All examples use a Bearer token (see [API authentication](https://heykiku.com/help/api-authentication)). For the complete list of endpoints with request/response shapes, see the [API reference](/api-reference).

## List documents

`GET /api/documents` returns documents the key's owner can see, filtered by visibility (general, internal, sensitive). Supports cursor pagination.

```bash
curl -H "Authorization: Bearer kiku_live_..." \
  "https://heykiku.com/api/documents?search=onboarding&limit=20"
```

Query parameters:

- `search` — case-insensitive substring match on the document filename (max 100 characters)
- `tagId` — filter by access tag (the visibility tier)
- `folderId` — filter by folder
- `status` — one of `pending`, `processing`, `pending_review`, `approved`, `complete`, or `failed`
- `staleness` — `due` (review date reached) or `overdue` (review date passed). Approver-only: a key whose owner can't approve gets a 403. Takes precedence over `status` when both are sent
- `cursor` + `limit` — keyset pagination, 1–100 per page (default 20)

The response nests `hasMore` and `cursor` under a `pagination` object:

```json
{
  "documents": [ /* ... */ ],
  "pagination": { "hasMore": false, "cursor": null }
}
```

## Upload a document

`POST /api/documents` (multipart/form-data). Requires `write` scope.

```bash
curl -X POST \
  -H "Authorization: Bearer kiku_live_..." \
  -F "file=@./brief.pdf" \
  -F "accessTagId=<tag-uuid>" \
  -F "folderId=<folder-uuid>" \
  https://heykiku.com/api/documents
```

Call `GET /api/access-tags` first to find valid `accessTagId` values for your workspace. Each tag maps to a visibility tier — uploading to the wrong tier is the most common cause of "user can't find the document later."

## List folders and tags

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

Folders are a workspace-level organizational layer. Access tags are the visibility tier (`general`, `internal`, `sensitive`).

## Create a folder

`POST /api/folders` requires `write` scope and a valid `accessTagId`:

```bash
curl -X POST \
  -H "Authorization: Bearer kiku_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Q3 briefs","accessTagId":"<tag-uuid>"}' \
  https://heykiku.com/api/folders
```

## Read past conversations

`GET /api/conversations` lists past chats; `GET /api/conversations/{id}` returns one with its messages array.

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

The `source` field on each conversation is `web` (started from the dashboard) or `mcp` (started by an MCP client — either with an API key or via OAuth). A third value `api` is reserved for a future REST send endpoint; no conversations carry this value today. `apiKeyNameSnapshot` records which key or OAuth client opened the conversation — useful when auditing which integration generated which traffic.

## What's not in the REST API

**Sending a chat message is not a REST endpoint.** Conversation reads are REST; sends use a streaming web protocol that doesn't suit SDK codegen. For now, the REST API is read-only for conversations. Send-via-API capability is being rebuilt and will return through a separate channel.

**Workspace administration is not in the REST API.** Team management, billing, and workspace settings are dashboard-only — there's no Bearer surface for these.