Updating Figures from a Script

If your figures come out of a program — charts drawn from data, diagrams generated from source files, plots from an analysis — you can have that program send them straight to Inkwell. Each upload replaces the picture in its figure and leaves the caption, number, size and position alone. Run the script again whenever the data changes and the book stays current.

What you need

• An API key for the project. An assistant can set one up for you (see below), or open Tools → API Keys and click Generate Key. You get a key and a secret; the secret is shown only this once, so copy both somewhere safe — an environment variable or a file your script reads, never the script itself. A key belongs to one project, and you can revoke it from the same dialog. See Tools.
• A figure key for each picture. Every figure has a hidden key that the API uses to find it. A figure you insert from the toolbar gets a random one, so it is easiest to choose your own names, like sales-by-region, using letters, digits, hyphens and underscores. The next two sections describe two ways to set them up.

Sending a picture

Send the file's bytes with a POST to https://inkwell.net/api/v0/figures/<figure key>. Sign in with HTTP Basic authentication, using the key as the username and the secret as the password:

curl --fail -u "$INKWELL_KEY:$INKWELL_SECRET" \
  --data-binary @charts/sales-by-region.png \
  https://inkwell.net/api/v0/figures/sales-by-region

Inkwell works out the file's format from its contents. PNG, JPEG, SVG and PDF are stored as they are, and SVG and PDF stay sharp at any size. Other image formats, such as WebP, GIF and TIFF, are converted to PNG. A successful upload returns an empty 200 response. A wrong key or secret returns 403, a file Inkwell can't read returns 400, and so does a figure key with characters other than letters, digits, hyphens and underscores.

Where the picture goes

If a figure in the project already has that key, its picture is replaced, everywhere the key appears. Anyone with the project open sees the new picture.

If no figure has that key yet, the picture waits as a pending figure. While any are waiting, the Insert Figure button opens a list of them instead of the file chooser. Click a picture to place it at your cursor, or remove the ones you don't want. That figure takes the key, so later uploads replace it in place. The file chooser returns once the list is empty.

Moving a figure keeps its key, whether you drag it or cut and paste it. A copy gets a new key, so uploads won't reach the copy.

Each upload is saved as a new picture and recorded as a change in the project's history, even if the file hasn't changed. Have your script send only the files that changed.

With an AI assistant

If your figures are made by code in a project folder and you use an assistant connected to Inkwell, such as Claude Code, the assistant can do the setup for you. Ask it something like:

Set up a script that uploads the charts in figures/ to my book and puts each one where it belongs.

The assistant reads the book to decide where each picture goes. It reuses the keys of figures that are already there, and for new pictures it adds empty figures with captions and keys named after the files. Those additions arrive as suggested edits for you to review. It then writes a script in your folder that uploads every file to its key.

The assistant also sets up the API key. It creates the key and writes it straight into a .env file in your folder that git ignores, without the secret ever appearing in the conversation. The key is listed under Tools → API Keys with the assistant's name, and you can revoke it there like any other. This only works when the assistant can edit the project.