> **Shapeless documentation index**
> Fetch https://shapelessai.com/llms.txt to discover every page before exploring further.
> Every page also answers Markdown: append `.md` to its path, or send `Accept: text/markdown`.

# Vercel AI SDK

The shapelessai-ai-sdk package: list connected accounts, schedule or publish a post, and read post status as AI SDK tools, with approval before anything goes out.

*Verified 2026-10-15. Source: https://shapelessai.com/docs/ai-sdk*

`shapelessai-ai-sdk` is a set of [Vercel AI SDK](https://ai-sdk.dev) tools: drop them into
`generateText` or `streamText` and the model can read the social accounts you connected,
schedule or publish a post on one of them, and check what went live. It calls the same
[API](/docs/api) every other door does, with an API key.

## Install

```bash
npm install shapelessai-ai-sdk ai
```

Node 18 or newer. `ai` 6 or newer and `zod` 3.25 or 4 are peer dependencies. Source:
[github.com/FirstClassTree/shapelessai, integrations/ai-sdk](https://github.com/FirstClassTree/shapelessai/tree/main/integrations/ai-sdk).

## Set the key

Mint a key under [Settings, API keys](https://shapelessai.com/studio/api-keys) with the `read` and
`publish` scopes ([Authentication](/docs/auth)), and set it as `SHAPELESSAI_API_KEY`. Every factory
also takes `{ apiKey }` directly.

## Use the tools

```ts
import { generateText, isStepCount } from "ai";
import { shapelessaiTools } from "shapelessai-ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  prompt: 'Schedule "We just shipped dark mode" to my LinkedIn in the next free slot.',
  tools: shapelessaiTools(),
  stopWhen: isStepCount(5),
});
```

| Tool | What it does | Input |
| --- | --- | --- |
| `listAccounts` | The connected accounts a post can go to, with the `connectionId` the other tools take. Call it first. | `platform?` (for example `"linkedin"`) |
| `createPost` | A post on one account: the account's next free queue slot by default, a set time with `scheduledAt`, or right away with `publishNow`. | `connectionId`, `text`, `scheduledAt?` (ISO 8601), `publishNow?` |
| `listPosts` | Recent posts with status, scheduled time, the live URL once published, and the error when one failed. | `status?`, `limit?` (1 to 50, default 20) |

Each tool is also exported on its own (`listAccounts()`, `createPost()`, `listPosts()`), so an
agent that only reads can carry only the readers. Every factory takes `{ apiKey, baseURL, needsApproval }`.

## Approval before a post

`createPost` ships with `needsApproval: true`: the AI SDK pauses before the tool runs and your app
decides whether the post goes ahead, the same gate the hosted [MCP server](/docs/mcp) puts in
front of every tool that publishes. Pass `createPost({ needsApproval: false })` for an agent that
is allowed to post on its own, for example one that only ever queues.

A post with no time and no `publishNow` takes the next free queue slot on purpose: nothing goes
out at an odd hour because the model left a field blank. The queue, the timings and every refusal
the rail can answer with are on [Posts](/docs/posts).

## What comes back

`createPost` answers `{ id, status, scheduledAt, url, error }`: `status` is `scheduled` for a
queued or timed post, `published` with a `url` for one that went out now. `listPosts` answers the
same shape per post, plus `connectionId`, `platform`, `text` and `publishedAt`.

A refused key answers an error that names where to mint a new one. A platform rule the post
breaks answers the rule itself ([Platforms](/docs/platforms)). On the Free plan the eleventh post
of a UTC day answers the day that is full ([Posts](/docs/posts#the-free-day)).

## Questions

### Does the AI SDK integration cover the whole API?

No. It carries the three tools an agent in an app needs most: accounts, create a post, read posts.
Everything else, from media generation to jobs and Brand Memory, is one `fetch` away on the
[API](/docs/api), or every tool at once on the hosted [MCP server](/docs/mcp).

### Which models does it work with?

Any model the AI SDK can call tools with. The tools are plain `tool()` definitions with Zod
input schemas; the example above uses the AI Gateway model string, and a provider model works the same way.