Simplified

Create a new context document and link it to the brand kit. **Two creation modes:** 1. **Link existing:** Provide `document_id` to link an existing KnowledgeDoc. 2. **Inline creation:** Provide `doc_type` and `name` (plus optional `description`, `data`, `content`) to create a new KnowledgeDoc and link it automatically. **Singleton constraint:** For predefined types (brand_voice, icps, usps, etc.), only one document per type per brandkit is allowed. Attempting to create a duplicate will return a 400 error. The `canonical_key` is auto-set from `doc_type` if it matches a predefined type. **Path Parameters:** - **brand_id**: Brand kit UUID

api_createContextDocument

Delete the link between a brand kit and a context document. If the underlying KnowledgeDoc is not linked to any other brandkit, it is automatically deleted (orphan cleanup). **Path Parameters:** - **brand_id**: Brand kit UUID - **document_link_id**: Either the context-document link UUID (BrandKitContextDocument ID) OR the underlying KnowledgeDoc UUID — the endpoint resolves both.

api_deleteContextDocument

Retrieve one linked context document, including its full content. The `document_link_id` may be EITHER the junction (BrandKitContextDocument) UUID returned by `listContextDocuments`, OR the underlying KnowledgeDoc UUID — the server resolves either form. Use this when you already have a document ID and want its content. To find a document by its canonical type (e.g. `brand_voice`) instead, use `getContextDocumentByType`. To list all documents on a kit, use `listContextDocuments`. **Path Parameters:** - **brand_id**: Brand kit UUID - **document_link_id**: Either the context-document link UUID (BrandKitContextDocument ID) OR the underlying KnowledgeDoc UUID — the endpoint resolves both.

api_getContextDocument

Retrieve a single context document by its canonical type key. Returns the full KnowledgeDoc directly (not the junction wrapper). Only returns active documents (`is_active=true`). **Path Parameters:** - **brand_id**: Brand kit UUID - **context_type**: Canonical type key to retrieve

api_getContextDocumentByType

List all context documents linked to a brand kit. Supports filtering by `canonical_key`, searching by document name or type, and ordering by created/modified timestamps. **Path Parameters:** - **brand_id**: Brand kit UUID

api_listContextDocuments

Update the content of a linked context document. Changes are applied to the underlying KnowledgeDoc, and its version is automatically incremented. **Path Parameters:** - **brand_id**: Brand kit UUID - **document_link_id**: Either the context-document link UUID (BrandKitContextDocument ID) OR the underlying KnowledgeDoc UUID — the endpoint resolves both.

api_updateContextDocument

Create a new long-form document rendered in the Quill editor. Content is stored as Quill Delta JSON (ops array). Used by AI-writer skills (Essay Writer, Article Writer) to persist generated markdown content into an editable document. The returned document is immediately openable at `/ai-writer/document/{space_or_organization}/{id}` in the Simplified web app. To convert markdown content into the required Quill Delta shape, call `markdown_to_quill_delta` from the writers toolkit before passing to this endpoint.

api_createDocument

Returns how many Simplified **credits** the current workspace has left. Credits are the shared currency spent by AI actions — image generation, video generation, and other AI tools all draw down the same balance. Call this tool when: - the user asks about their credits / balance / quota / "how much is left"; - **before** an AI generation (e.g. `api_generateImage`) when you want to confirm there's enough balance to avoid a mid-run failure; - **after** a generation fails with an out-of-credits / quota error, to report the remaining balance back to the user. No inputs. The response is a `credits` object: - `credits.remaining` — credits still available to spend - `credits.used` — credits consumed in the current period - `credits.total` — total credits allotted for the period - `credits.trial` — extra trial allowance (only present when on trial)

api_getCreditBalance

Assign or reassign an AI agent (Chatbot) to a project item. The agent will be responsible for processing or executing the item. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID - **id**: Item ID (UUID)

api_assignAgentToItem

Create a new item within the project. The accepted fields vary by resourcetype — inspect a GET response to see available fields for the target type. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID

api_createProjectItem

Retrieve a single project item by its ID. Returns the full item object including status, assignees, and metadata. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID - **id**: Item ID (UUID)

api_getProjectItem

List all items within a project. Items represent individual tasks, content pieces, or entries within the parent project. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID

api_listProjectItems

Move a ProjectItem to a new position within the project. Updates the ordering of items accordingly. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID - **id**: Item ID (UUID)

api_reorderProjectItem

Soft-delete a single item within a project — sets `is_deleted=true`. The item stops appearing in `listProjectItems`/`getProjectItem` but is not purged, so it is recoverable server-side. Requires the parent project ID and matching `resourcetype`. To remove the whole project, use `deleteProject`. **Path Parameters:** - **resourcetype**: Project type selector - **parent_lookup_project_id**: Parent project ID - **id**: Item ID (UUID)

api_deleteProjectItem

Sends a single notification. It is routed through the notification registry, which determines delivery channels (in-app, websocket, email, Slack) based on the category.

notify_sendAgentNotification

Create a project of the given `resourcetype`. `title` is the common field; type-specific fields go under `data` (varies by resourcetype — inspect a `getProject` response for the target type to see its shape). Returns the new project's UUID, used for `createProjectItem`, `listProjectItems`, etc. **Path Parameters:** - **resourcetype**: Project type selector (the model name). The API is polymorphic — the same URL structure serves different project types based on this value. Valid values: - `Project` — generic projects (the default for most content). - `AdCreativeProject` — ad-creative projects (specialized fields). Use the same value on create, get, list, and delete for a given project.

api_createProject

Export specified ProjectItems to a partner integration (e.g. WordPress, social media). Provide the partner account ID and the list of item UUIDs to export. **Path Parameters:** - **resourcetype**: Project type selector - **id**: Project ID

api_exportProjectItems

Retrieve a single project by its ID. Returns the full project object with all fields for the given resourcetype. **Path Parameters:** - **resourcetype**: Project type selector - **id**: Project ID (UUID or integer depending on type)

api_getProject

List projects of the given `resourcetype` in the workspace, paginated and newest-first. Returns project objects with their UUIDs — needed for `getProject`, `listProjectItems`, and `deleteProject`. Filter with `?search=<title>`. Pass the same `resourcetype` you created the projects with. **Path Parameters:** - **resourcetype**: Project type selector (the model name). The API is polymorphic — the same URL structure serves different project types based on this value. Valid values: - `Project` — generic projects (the default for most content). - `AdCreativeProject` — ad-creative projects (specialized fields). Use the same value on create, get, list, and delete for a given project.

api_listProjects

Soft-delete a project — sets `is_deleted=true`. The project and its items stop appearing in `listProjects`/`getProject` but are not purged from the database, so this is recoverable server-side. `resourcetype` must match the project's type (`Project` or `AdCreativeProject`) — the same value used to create it. **Path Parameters:** - **resourcetype**: Project type selector - **id**: Project ID (UUID or integer depending on type)

api_deleteProject

Retrieve the status and result of an async task by its `task_id`. Status values: PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED. Note: for most async tools (`generateImage`, media/* operations) the toolkit middleware **already polls this for you** and returns the final result — you rarely need to call it directly. Use it manually only when a long job (e.g. video generation) exceeds the auto-poll window and you got a `task_id` back. **Path Parameters:** - **task_id**: Celery task ID

api_getTaskResult

Fetch a single workspace (organization) by its integer ID — name, plan, settings, and metadata. The API token is bound to one workspace; pass that workspace's ID here to read its details. **Path Parameters:** - **id**: Workspace/Organization ID

api_getWorkspace

Returns the authenticated caller's workspace context in a single call — no workspace ID required. Everything is derived from the auth token or `Organization` header. Response includes: - `user` — id, first_name, last_name, email of the requesting user - `workspace` — id, name, slug, is_active, and settings (timezone, language, start_of_week) - `teamspaces` — active spaces visible in workspace context (id, name, slug, is_active) Do not use this response as the membership authority for `space_id`. Call `listTeamspaces` to resolve IDs the current user can scope into.

api_getWorkspaceInfo

List the teamspaces (Spaces) the current user is a member of, within the token's workspace. Use this to resolve a teamspace before scoping other calls: each returned `id` (integer) is the value you pass as the `Space` header (or `--space` / `space_id`) to narrow a request to that teamspace. The token stays bound to its one workspace — this does not switch workspaces, it only lists the sub-spaces you can scope into. Supports `?search=<name>` to filter by teamspace name and `?expand=settings`. Each item: `{id (int), name, slug}`.

api_listTeamspaces

Append additional drafts to a review bundle previously created via `createSocialMediaReviewBundle`, without recreating it. The operation is idempotent — a draft already present in the bundle is silently skipped, not duplicated. Draft IDs come from `getSocialMediaDrafts`. Returns the updated bundle, including the full list of drafts and the shareable review URL.

social_addDraftsToSocialMediaReviewBundle

Create a review bundle, optionally seeding it with drafts. A review bundle groups social media drafts under a single shareable review URL so collaborators or clients can approve content before it is scheduled or published. Pass `draft_ids` to seed the bundle on creation, or create an empty bundle and append drafts later via `addDraftsToSocialMediaReviewBundle`. Draft IDs come from `getSocialMediaDrafts`. The response includes a `linkToReview` URL to share with reviewers.

social_createSocialMediaReviewBundle

Step 1 — discover the dynamic per-(model, capability) parameter schema before calling `generateImage` or `generateVideo`. A single unified endpoint serves both image and video engines, selected by the required `type` query param. Response modes (driven by which query params you pass): - `type` only → `{models: [...]}` — list every registered engine of that type, its capabilities, and metadata (incl. `credits_per_image` / `estimated_time`). Use this to pick a `model_id`. - `type` + `model_id` → single-model detail with capabilities map. - `type` + `model_id` + `capability` → the full FieldDescriptor schema for that (model, capability) pair (labels, field_type, required flags, enum_values, defaults). This is the contract that `generateImage` / `generateVideo`'s `parameters` must match. Use this before generating — it eliminates 400 errors on invalid / missing parameter keys.

api_getModelFields

Generate AI images from a text prompt, a reference image (image-to-image), or for editing — across multiple models (Flux, Gemini, GPT Image, Recraft, SeedDream, Ideogram, etc.). ## Two-step workflow 1. **Discover** — call `getModelFields` with `type=image`, `model_id=<chosen model>`, `capability=<chosen capability>` to learn the exact `parameters` keys, types, valid enums, and defaults for the model/capability combination. The accepted `parameters` are **dynamic** per (model, capability); discovering first avoids 400 errors. 2. **Generate** (this endpoint) — POST `{model, capability, parameters}`. This call **blocks and returns the final result** — apikit polls the generation task internally, so you do **not** call `getTaskResult` yourself. `storage` controls where the result is kept: - "asset" — saved to your asset library for reuse (recommended) - "transient" — temporary, not saved - "default" — kept in the image gallery

api_generateImage

Generate AI video using the unified V2 generation system. Supports Kling, WAN, VEO, Sora and others across capabilities: text→video, image→video, multi-image, first-last-frame, video→video. ## Three-step workflow 1. **Discover** — call `getModelFields` with `type=video`, `model_id=<chosen model>`, `capability=<chosen capability>` to learn the exact `parameters` keys, types, valid enums, and defaults for the model/capability combination. 2. **Submit** (this endpoint) — POST `{model, capability, parameters}`. Response is `{id, art_variation_id}` (and a `task_id` you can ignore — see below). 3. **Poll** — call `getVideoVariation` with the returned `id` (as `art_id`) and `art_variation_id`, repeating with a short delay (10s) until `job_status` is terminal (`DONE` or `FAILED`). The rendered video URL is in `payload.output` / `asset_references`. ## Why `task_id` is misleading here The endpoint also returns a `task_id`, but it tracks the *submission* Celery task that hands the request off to FAL/Kie — it flips to SUCCESS almost immediately, well before the actual video is rendered. **Do not call `getTaskResult` on this `task_id`** — it tells you nothing useful about generation completion. Always poll `getVideoVariation` instead. The apikit middleware strips `task_id` from this response automatically to avoid confusion. ## Storage modes - `default` — persists into the AiImageArt gallery (recommended). - `transient` — generated without surfacing in the gallery; useful for one-shot agent runs. - `asset` — saves the rendered video as a standalone reusable `TldrAsset` (no gallery entry).

api_generateVideo

Convert text to spoken audio using the voice referenced by `voice_id` (get voices from `listVoices`). `storage` controls whether the audio is saved. Set `use_ssml: true` ONLY when `text` contains SSML markup like `<speak>` / `<break>` / `<emphasis>`. For plain prose leave it false — providers handle punctuation pacing well and SSML support varies. Storage modes: - `default` — returns the audio URL only (can expire) - `asset` — also saves it to your asset library for reuse **Path Parameters:** - **voice_id**: Voice UUID from listVoices `voices[].id`

api_generateAudio

Retrieve a single voice by its UUID. Use this to resolve a bare `voice_id` — one the user picked in a voice picker, or a saved preference — back to its attributes without re-listing the whole catalog: `gender` (0=Male, 1=Female, 3=Neutral), `voice_name`, `is_premium`, `description`, and `supports_instructions` (whether the voice honors the `instructions` hint on generateAudio). The response is a single voice object — the same shape as one entry of `listVoices`'s `voices[]`. Resolution is workspace-scoped: a voice owned by another workspace (and not globally published) returns 404. **Path Parameters:** - **voice_id**: Voice UUID (the `id` from a `listVoices` `voices[]` entry).

api_getVoice

List voices available to the current workspace, filtered by language. `language_code` is the ONLY required parameter — use an exact BCP-47 locale (`en-US`, `en-GB`, `fr-FR`, `hi-IN`, `ja-JP`). Combine with `is_premium=true` for a short, high-quality shortlist. The optional filters (`gender`, `provider`, `engine`, `is_premium`, `language_name`, `search`) all default to an empty string `""`, which means "no filter — return everything". Leave them at `""` unless the user explicitly asked to filter. Do NOT substitute `0`/`false` for "no filter": `0` is a REAL value (gender 0 = Male, provider 0 = Google, engine 0 = Neural), so sending it silently narrows the list. The empty-string default is the ONLY correct "unset" value. Response: - `voices[]`: `id` (uuid), `voice_name`, `language_code`, `avatar`, `voice_sample`, `gender` (0=Male, 1=Female, 3=Neutral), `is_premium`, `description`, `supports_instructions` (bool — `true` if the voice honors the `instructions` style/pace hint on generateAudio). Use `id` as `voice_id` in generateAudio. To re-resolve a single known `voice_id` (e.g. from a saved preference) without re-listing, use `getVoice`. - `languages[]`: distinct `{language_code, language_name}` pairs. To resolve a known `voice_name` (e.g. from an avatar roster) to its `id`, pass `voice_name` + `language_code` — that pair is unique, and the `id` differs per locale, so the name must be re-resolved whenever the language changes. Always check the entry you use actually has that `voice_name` rather than trusting `voices[0]` — see the `voice_name` parameter.

api_listVoices

Step 3 — poll this endpoint after `generateVideo`. Read `job_status`: - **Non-terminal**: `CREATED`, `PENDING`, `PROCESSING`, `RENDERING`, `UPDATED` — keep polling. 10s is a reasonable interval. - **Terminal**: `DONE` (success — `payload.output` and `asset_references` are now populated with the rendered video URL) or `FAILED` (error — inspect `payload.errors`). Generation is webhook-driven (FAL / Kie call back into djapp when rendering finishes), so the row updates asynchronously — there is no `task_id` to short-circuit polling. **Path Parameters:** - **art_id**: AiImageArt UUID returned as `id` from `generateVideo`. - **variation_id**: AIArtVariation UUID returned as `art_variation_id` from `generateVideo`.

api_getVideoVariation

Detects the subject and blurs the background. Synchronous — returns image_url directly.

media_blurBackground

Convert an image from one container format to another (jpg, jpeg, png, webp, gif, bmp, tiff). Pass the source `image_url` and the target `output_format`. This changes the file format ONLY — for pixel-level edits (background removal, upscale, inpaint) use the other image tools in this module. Async — returns a task_id (auto-polled).

media_convertImageFormat

Fill a masked region of an image with AI-generated content described by `prompt`. Requires a mask (`mask_url` or `mask_base64`) marking WHERE to fill. Use this when you have a specific region to replace; for removing an object by description (no mask) use `magicInpaint`; to extend the image past its edges use `imageOutpainting`. Async — returns a task_id (auto-polled).

media_generativeFill

Remove or replace objects in an image, guided by `prompt`, with no mask needed (the model locates the target). Use for "remove the person" / "replace the car with a bike". With an explicit mask region use `generativeFill`; to extend beyond the borders use `imageOutpainting`. Async — returns a task_id (auto-polled).

media_magicInpaint

Extend an image BEYOND its original borders (uncrop), generating new surrounding content from `prompt`. Requires `mask_url` marking the new area. Different from `generativeFill` (fills a region inside the image) and `magicInpaint` (edits existing content). Async — returns a task_id (auto-polled).

media_imageOutpainting

Removes the background from an image. Returns a task_id — poll for result.

media_removeBackground

Replace ONLY the background behind the detected subject — with a solid color, another image, or transparency. Set `replace_type` to `color` (needs `replace_color`), `image` (needs `replace_image`), or `transparent`. To blur rather than replace use `blurBackground`; to cut the subject out entirely use `removeBackground`. Async — returns a task_id (auto-polled).

media_replaceImageBackground