Plotwork

Import a Plotwork diagram

Has Plotwork paint the diagram as a PNG, keeps it as a media file with alt text, and answers the file, ready: put its id in a post's mediaIds.

POST/v1/plotwork/diagrams/{id}/import

TL;DR

Question	Answer
What does it do?	Import a Plotwork diagram.
What does it need?	An API key or an OAuth access token.
What does it take?	A JSON body with the fields below, and `id` in the path, and `idempotency-key` in a header.
What does it return?	Status 201 with a body of type `Media`.
In the SDK?	`flung.plotwork.importDiagram()`
As an MCP tool?	`attach_plotwork_diagram`
What can go wrong?	`401` Missing, unknown, revoked or expired API key; `404` No such diagram in the connected account; `409` Plotwork is not connected (`plotwork_not_connected`), or must be connected again (`plotwork_reconnect`), in the portal; `422` The request failed validation; `429` Too many requests for this credential; wait for `retry-after` seconds; `502` Plotwork could not be reached or refused for a moment (`plotwork_unavailable`); `503` Plotwork is not set up on this server (`not_configured`). Every failure has the same error shape.

Example

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

1import { Flung } from '@flung.dev/sdk'2
3const flung = new Flung({ apiKey: process.env.FLUNG_API_KEY! })4const result = await flung.plotwork.importDiagram({5  id: '0b7e3c1a-5d2f-4c88-9a41-6f0e2d9b7c35',6})

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

A successful answer looks like this:

1{2  "id": "med_aaaaaaaaaaaaaaaaaaaaaaaa",3  "contentType": "image/jpeg",4  "filename": "string",5  "altText": "string",6  "bytes": 1,7  "status": "pending",8  "preview": {9    "status": "processing",10    "thumbnailUrl": "string",11    "hlsUrl": "string",12    "dashUrl": "string",13    "durationSeconds": 114  },15  "createdAt": "2026-11-01T09:00:00.000Z"16}

Path parameters

Field	Type	Required	Description
`id`	`string`	yes	A diagram id from the list.

Header parameters

Field	Type	Required	Description
`idempotency-key`	`string`	no	Any unique string, such as a UUID. A retry with the same key and body within 24 hours gets the first answer instead of running again.

Request body

The body has the type an object, with the fields below.

Field	Type	Required	Description
`scheme`	`"light" \| "dark"`	no	Painted light or dark. A picture drawn for one scheme keeps it. default "light".
`width`	`integer`	no	The width in pixels; 1600 suits every network. minimum 800; maximum 2400; default 1600.
`altText`	`string`	no	Defaults to the diagram's name. at least 1 character; at most 1000 characters.

Responses

Status	Meaning	Body
201	The media file, `ready`.	`Media`
401	Missing, unknown, revoked or expired API key.	`Error`
404	No such diagram in the connected account.	`Error`
409	Plotwork is not connected (`plotwork_not_connected`), or must be connected again (`plotwork_reconnect`), in the portal.	`Error`
422	The request failed validation.	`Error`
429	Too many requests for this credential; wait for `retry-after` seconds.	`Error`
502	Plotwork could not be reached or refused for a moment (`plotwork_unavailable`).	`Error`
503	Plotwork is not set up on this server (`not_configured`).	`Error`

Response body

A 201 answer has the type Media.

Field	Type	Required	Description
`id`	`string`	yes
`contentType`	`MediaType`	yes	What the file really is, read from its first bytes once uploaded.
`filename`	`string \| null`	yes
`altText`	`string \| null`	yes	The alt text the file was imported with, such as a Plotwork diagram's name. Null for an upload.
`bytes`	`integer \| null`	yes
`status`	`"pending" \| "processing" \| "ready" \| "failed"`	yes	`pending` until its bytes arrive; `ready` once a post can use it.
`preview`	`object \| null`	yes	Videos only, where previews are set up: a thumbnail. Read the file again while `processing`.
`preview.status`	`"processing" \| "ready" \| "failed" \| "skipped"`	yes	`skipped` when the video is over 100 MB or this month's thumbnail allowance is used up. Posts never wait for a preview; they use the file as uploaded.
`preview.thumbnailUrl`	`string \| null`	yes	A JPEG frame one second in, 640 pixels wide, at an address that does not expire.
`preview.hlsUrl`	`string \| null`	yes	Always null for now: streaming versions are not made.
`preview.dashUrl`	`string \| null`	yes	Always null for now.
`preview.durationSeconds`	`number \| null`	yes	Always null for now.
`createdAt`	`string`	yes

Doc	Why
API reference	Every endpoint
Schemas	Every request and response type
Errors	Every error code and what to do about it
`attach_plotwork_diagram`	The same operation as an MCP tool