# Integrations: Plotwork

> Page: https://docs.flung.dev/plotwork. Index of every page: https://docs.flung.dev/llms.txt

Connect a Plotwork account to a workspace, then pull its diagrams into posts as images, each with its name as alt text.

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Lists the diagrams of the Plotwork account the workspace connected, private ones included, and imports one as a PNG file ready for `mediaIds`. |
| Who connects it? | A member of the workspace, once, from Integrations in the Flung portal. Plotwork asks them to approve Flung for their own account or one of their Plotwork organisations. |
| What may Flung do in Plotwork? | Read the library, and the account's name and email. Flung never changes or publishes a diagram. |
| How big is the image? | 1,600 pixels wide by default, from 800 to 2,400, painted by Plotwork light or dark (a diagram drawn in one scheme keeps it). It counts toward the plan's media storage like every other file. |
| Can an agent use it? | Yes. An agent lists the diagrams and attaches one; it cannot connect Plotwork for you. |

## Connect Plotwork

Open Integrations in the Flung portal. Plotwork is the featured card at the top: choose it, then Connect Plotwork. Plotwork asks you to sign in if you have not, shows what Flung asks for, and lets you choose your own account or an organisation's library. Approve, and you come back to Flung, connected.

The workspace has one Plotwork connection. It shows the address it is connected as. An owner, or the person who connected it, can disconnect it; that ends the sign-in in Plotwork too. It also ends by itself when the person who connected it leaves the workspace, so their library is never read for a workspace they are no longer in.

## Pick a diagram in the portal

On the Plotwork page, Browse diagrams opens the picker: search by name or folder, choose a diagram to see it larger, pick Light or Dark, and import it. Flung gives back the media id, ready to put in a post.

## List the diagrams

**curl**

```bash
curl -X GET 'https://api.flung.dev/v1/plotwork/diagrams?q=checkout' \
  --header "Authorization: Bearer $FLUNG_API_KEY"
```

**TypeScript**

```ts
import { Flung } from '@flung.dev/sdk'

const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })
const result = await flung.plotwork.listDiagrams({
  q: 'checkout',
})
```

**fetch**

```js
const response = await fetch('https://api.flung.dev/v1/plotwork/diagrams?q=checkout', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`,
  },
})
if (!response.ok) throw new Error((await response.json()).error.message)
const result = await response.json()
```

`q` keeps to diagrams whose name or folder holds the words, ignoring case, across the whole library. Follow `nextCursor` for the next page.

## Import one for a post

**curl**

```bash
curl -X POST 'https://api.flung.dev/v1/plotwork/diagrams/0b7e3c1a-5d2f-4c88-9a41-6f0e2d9b7c35/import' \
  --header "Authorization: Bearer $FLUNG_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{}'
```

**TypeScript**

```ts
import { Flung } from '@flung.dev/sdk'

const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })
const result = await flung.plotwork.importDiagram({
  id: '0b7e3c1a-5d2f-4c88-9a41-6f0e2d9b7c35',
})
```

**fetch**

```js
const response = await fetch('https://api.flung.dev/v1/plotwork/diagrams/0b7e3c1a-5d2f-4c88-9a41-6f0e2d9b7c35/import', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.FLUNG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({}),
})
if (!response.ok) throw new Error((await response.json()).error.message)
const result = await response.json()
```

The answer is a media file, `ready`, with `altText` set to the diagram's name unless you sent your own. Put its `id` in `mediaIds` when you create or change a post, as with every other image.

## With an AI agent

Ask in plain words, such as "Post our checkout flow diagram from Plotwork to LinkedIn tomorrow at nine". The agent lists the diagrams, attaches the one you meant, and schedules the post with it. If the workspace has not connected Plotwork, it tells you to connect it in the portal first.

## When it refuses

| Code | What to do |
|---|---|
| `plotwork_not_connected` | Connect Plotwork in the portal, under Integrations. |
| `plotwork_reconnect` | Plotwork ended the connection, for example because it was disconnected in Plotwork. Connect it again. |
| `plotwork_unavailable` | Plotwork did not answer. Try again in a minute. |
| `not_configured` | Plotwork is not set up on this server. |
| `media_too_large` | The diagram is too big for Plotwork to paint, or its PNG is over 20 MB. Import it narrower, or split the diagram. |