Add an image to a library folder

POST

/workspaces/{workspaceId}/library/folders/{folderId}/items

import { FloraClient } from '@flora-ai/flora';

const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });

const library = await client.workspaces.library.addFolderItem({
  workspaceId: '<workspaceId>',
  folderId: '<folderId>',
  type: 'image',
  source: 'https://media.flora.ai/example.png',
  text: 'A cool prompt clipped from a tweet',
  description: 'Product hero shot',
});
console.log(library);

Fetches an image from a public HTTPS URL (SSRF-safe) and saves it into the given library folder as a media node. Used by the Web Clipper’s send pipeline, one call per selected image. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

Error responses use the standard error body.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

Workspace identifier

string

/^ws_\S+$/

Workspace identifier

folderId

required

Library folder identifier

string

/^libfolder_\S+$/

Library folder identifier

Request Body

Media type application/json

object

type

Kind of item to save.

string

default: image

Allowed values: image text

source

Public HTTPS URL of the image to save (required when type=image). FLORA fetches the bytes server-side with SSRF protection (private/loopback/metadata IPs and redirects to them are blocked) and stores them.

string

text

Text to save as a text node (required when type=text).

string

description

Optional caption/label for the saved item

string

Responses

201

Image added to the library folder.

Media type application/json

object

saved_node_id

required

Saved node identifier

string

/^savednode_\S+$/

folder_id

required

Library folder identifier

string

/^libfolder_\S+$/

asset_id

Asset identifier

string

/^asset_\S+$/

url

Any of:

string

string format: uri

null

null

workspace_id

required

Workspace identifier

string

/^ws_\S+$/

Example

{
  "saved_node_id": "savednode_abc123",
  "folder_id": "libfolder_abc123",
  "asset_id": "asset_abc123",
  "workspace_id": "ws_abc123"
}