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

# RiteKit plugin

> Hashtag stats and suggestions, emoji, quote images, link shortening, person and company insights, and article extraction with RiteKit.

Use **RiteKit** through Corsair: one client, typed API calls.

Create a token in the [API Console](https://ritekit.com/developer/dashboard/) - RiteKit calls it a **Client ID**. It travels as the `client_id` query parameter on every call, which is the transport RiteKit documents for all endpoints.

Things to know before you call:

* **Credits, not requests, are the budget.** Each endpoint costs 1 or 2 credits and the monthly allowance is shared across all of them, so a `402` means the month's credits are gone: the plugin reports it as `isQuotaExhausted` and never retries, because waiting cannot refill them. The rate limit itself is 100 calls per second.
* **Two `401` messages mean different things.** A call with no Client ID gets `Endpoint is not accessible`; a Client ID RiteKit does not recognise gets `Verification failed`. Both are a `401`, and the plugin keeps RiteKit's `info` hint on the error because it usually names the fix.
* **Hashtag fields are named differently per route.** `hashtags.stats` returns rows under `stats` (and the tags it read under `hashtags`); `hashtags.suggestions` and `hashtags.forImage` return them under `data`; `hashtags.forUrl` returns them under `hashtags`; `hashtags.trending` returns `tags` and calls the image share `photos` where the others call it `images`. The response models follow each route rather than pretending they match.
* **The `color` number needs its legend.** A stats row's `color` is 0 unused, 1 overused, 2 good, 3 great, and `hashtags.stats` returns the labels in a `color` array beside the rows. `hashtags.trending`'s `green` filter is the same idea, and the API reads it as `1` rather than `true`.
* **`images` / `links` / `mentions` are percentages, not counts.** A value of `0.35` means 0.35% of the hashtag's tweets carry an image, which is why the fields are fractional.
* **`hashtags.stats` takes up to 100 tags in one call**, joined into a single comma-separated `tags` value. The plugin rejects a longer list rather than letting RiteKit truncate it.
* **`links.shorten` needs a Link Ad.** RiteKit answers `500` when `cta` is missing, so the plugin requires it. `links.listCtas` lists the account's Link Ads (a new account has `bit.ly`, no ad, and its own default ad); pass one of those ids as `cta`. Each shorten creates a new link and spends a credit, so a `5xx` on it is not retried.
* **`images.quote` and `images.animate` return the image itself.** The docs say each returns a URL, but the API answers with the PNG or GIF bytes. The plugin returns them as a data URL in `url`, with `contentType` and `bytes`. An animated GIF is a few hundred KB.
* **`companies.nameToDomain` is slow and returns `data`.** Live answers took about 18 seconds, so the plugin waits up to 60. The domains come back under `data`, best first.
* **`person.nameFromEmail` returns the name as one string**, such as `John Doe` in `info`, although the published sample shows `givenName` and `surname`. The schema accepts both.
* **`companies.logo` gives you two URLs.** `url` expires; `permanentUrl` is stable, but every view of it costs a credit, so store the permanent one and let a CDN fetch it.

**What you get:**

* 23 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/ritekit better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/ritekit better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/ritekit better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/ritekit better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { ritekit } from '@corsair-dev/ritekit';

export const corsair = createCorsair({
	plugins: [
		ritekit(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> No setup required yet. When you make your first request as a tenant, Corsair prompts for the API key.
>
> ```ts theme={null}
> ritekit()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'ritekit',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**Read stats for two hashtags**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.ritekit.api.hashtags.stats({
	tags: ['jobs', 'hello'],
});
```

**Shorten a link with a Link Ad**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.ritekit.api.links.shorten({ url: 'https://ritekit.com', cta: '6530' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/ritekit/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/ritekit/api.md)
>
> Every `ritekit.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.