# @flotiq/api

> Flotiq API

Latest version **1.1.2** (published 2026-08-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @flotiq/api
pnpm add @flotiq/api
yarn add @flotiq/api
bun add @flotiq/api
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.1.2 |
| Published | 2026-08-03 |
| First published | 2026-05-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 23.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Flotiq team |
| Maintainers | flotiq |
| Keywords | flotiq, cms, headless, content |

## Links

- npm: https://www.npmjs.com/package/@flotiq/api
- Repository: https://github.com/flotiq/flotiq-api
- Homepage: https://github.com/flotiq/flotiq-api#readme
- Issues: https://github.com/flotiq/flotiq-api/issues
- npm.io page: https://npm.io/package/@flotiq/api

## Dependencies (5)

- [axios](https://npm.io/package/axios.md) ^1.16.0
- [winston](https://npm.io/package/winston.md) ^3.19.0
- [progress](https://npm.io/package/progress.md) ^2.0.3
- [traverse](https://npm.io/package/traverse.md) ^0.6.11
- [form-data](https://npm.io/package/form-data.md) ^4.0.5

## Alternatives

- [ext-list](https://npm.io/package/ext-list.md) — 6.3M weekly downloads
- [@lexical/selection](https://npm.io/package/@lexical/selection.md) — 3.8M weekly downloads
- [@lexical/text](https://npm.io/package/@lexical/text.md) — 3.6M weekly downloads
- [@lexical/clipboard](https://npm.io/package/@lexical/clipboard.md) — 3.0M weekly downloads
- [@tiptap/extension-mention](https://npm.io/package/@tiptap/extension-mention.md) — 3.0M weekly downloads

## Recent versions

- 1.1.2 (latest) — 2026-08-03
- 1.1.1 — 2026-06-02
- 1.1.0 — 2026-06-02
- 1.0.0 — 2026-05-18

## README

# flotiq-api

Node.js CommonJS client for working with the Flotiq API. The package wraps Flotiq content type, content object, and media operations behind a single class built on top of `axios`, with request throttling and automatic retry handling for HTTP `429` responses.

## Features

- Fetch and update content type definitions
- Read, publish, create, patch, and delete content objects
- Download and upload media files
- Reuse cached API clients with `getFlotiqApi(...)`
- Throttle write traffic with `writePerSecondLimit`
- Retry requests after rate limiting using the `Retry-After` header when present

## Requirements

- Node.js
- Yarn

## Installation

Install dependencies in the repository root:

```bash
yarn install flotiq-api
```

## Usage

### Create a client

```js
const FlotiqApi = require('flotiq-api');

const api = new FlotiqApi('https://api.flotiq.com/api', 'YOUR_API_KEY', {
  batchSize: 100,
  batchSizeRead: 1000,
  writePerSecondLimit: 10,
});
```

### Reuse a cached client

```js
const { getFlotiqApi } = require('flotiq-api');

const api = getFlotiqApi('https://api.flotiq.com/api', 'YOUR_API_KEY', {
  batchSize: 100,
});
```

Clients created through `getFlotiqApi(...)` are cached by API URL, API key, and options.

### Fetch content objects

```js
const objects = await api.fetchContentObjects(
  'article',
  1,
  50,
  { field: 'internal.createdAt', direction: 'asc' },
  { status: { type: 'equals', filter: 'published' } }
);
```

### Create or update content objects in batches

```js
await api.persistContentObjectBatch('article', [
  {
    id: 'article-1',
    title: 'Hello Flotiq',
  },
]);
```

### Upload media from a remote URL

```js
const media = await api.uploadMediaFromUrl({
  fileName: 'hero.png',
  mime_type: 'image/png',
  url: 'https://example.com/hero.png',
});
```

## API Overview

### Constructor

```js
new FlotiqApi(flotiqApiUrl, flotiqApiKey, options)
```

Supported options:

- `batchSize`: write batch size, defaults to `100`
- `batchSizeRead`: read page size, defaults to `1000` or `batchSize` when provided
- `writePerSecondLimit`: maximum write throughput, defaults to `10`

### Content type definitions

- `fetchContentTypeDefinition(name)`
- `fetchContentType(internal = false)`
- `fetchContentTypeDefs()`
- `updateContentTypeDefinition(name, definition)`
- `deleteContentTypeDefinition(name)`
- `checkIfClear(ctds)`
- `createOrUpdate(remoteCtd, contentTypeDefinition)`

### Content objects

- `fetchContentObject(contentType, id, hydrate = 0)`
- `fetchContentObjects(contentType, hydrate = 0, limit, order, filters)`
- `persistContentObjectBatch(contentType, objects)`
- `patchContentObjectBatch(contentType, objects)`
- `deleteContentObjectBatch(contentType, objects)`
- `publishContentObject(contentType, object)`

### Media

- `fetchMediaFile(mediaUrl)`
- `uploadMedia(form)`
- `uploadMediaFromUrl(contentObject, existingImages = {})`

## Utilities

The repository also exposes helper utilities in `./src/util.js`:

- `camelize(str)`
- `readCTDs(directory)`
- `shouldUpdate(relatedContentObject, replacements)`
- `rateLimitInterceptor(axios, logger, defaultDelay)`
- `throttleInterceptor(axios, delay)`

Logging is handled with Winston in `./src/logger.js`.

## Development

Run the test suite:

```bash
yarn test
```

Run tests in watch mode:

```bash
yarn test:watch
```

## Notes

- The client sends the `X-Auth-Token` header for authentication.
- Requests are created with the `x-mode: preview` header.
- Batch writes show a terminal progress bar using the `progress` package.

---
_Source: https://npm.io/package/@flotiq/api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._