REST API

The Server AI Toolkit REST API contains endpoints for getting the available tools and executing tool calls

Base URL

The Tiptap Cloud base URL is:

BASE_URL=https://api.tiptap.dev

In on-premises deployments, the base URL may differ.

In the examples below, requests are written as BASE_URL/v4/ai/toolkit/....

Authentication

All requests must include this authentication header:

• Authorization: Bearer JWT, where JWT is a Tiptap Access Control JWT.

Sign the token server-side with these settings:

• Audience: AI
• Permissions: AI:Toolkit

To fetch and save Tiptap Cloud documents automatically, add the Documents audience and the Documents:Write permission. Documents:Write includes read and comment access.

See Authentication for how to create a key pair and sign tokens, and the authorization guide for the full setup.

import { SignJWT, importPKCS8 } from 'jose'

const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY, 'ES256')

const JWT_TOKEN = await new SignJWT({
  permissions: [
    { action: 'AI:Toolkit', resource: '*' },
    { action: 'Documents:Write', resource: 'your-document-id' },
  ],
})
  .setProtectedHeader({ alg: 'ES256' })
  .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID)
  .setAudience(['AI', 'Documents'])
  .setExpirationTime('30m')
  .sign(privateKey)

The previous App ID + secret authentication flow is documented under Legacy authentication.

Optional fields

Optional fields can be omitted, null, or undefined.

Endpoints

Fetch tool definitions

POST /v4/ai/toolkit/fetch-tools

Returns the prompt and tool definitions that you pass to your AI provider.

Request body:

• editorContext (object, required): The editor context returned by getEditorContext.
• tools (Record<string, boolean | ToolConfig>, optional, default: {}): Enables, disables, or configures tools. Tools are disabled by default.
• format ('json' | 'shorthand' | 'shorthandV2', optional, default: 'json'): Document format used by tool definitions and model output. See Tiptap Shorthand.

tools can contain these keys:

• tiptapRead (boolean, optional)
• tiptapEdit (boolean | { meta?: string }, optional): Set meta when you want the AI to include an extra metadata field on every edit operation, such as a short explanation.
• tiptapQuery (boolean | { meta?: string }, optional): Set meta when you want the AI to include an extra metadata field on every operation that changes the document. See tiptapQuery.
• getThreads (boolean, optional)
• editThreads (boolean, optional)
• readDocument (boolean, optional)
• replaceDocument (boolean, optional)
• createDocument (boolean, optional): Alias for replaceDocument.
• readSelection (boolean, optional)
• proofread (boolean | { meta?: string }, optional): Set meta when you want the AI to include an extra metadata field on every proofreading edit, such as a short explanation.
• readBoard, createShapes, arrangeShapes, createDiagram, updateShapes, deleteShapes, connectShapes and createDocFrame (boolean, optional): The board tools, for a whiteboard.

Response:

• systemPrompt (string): Add this to the system prompt for your AI request. It teaches the AI how Tiptap documents work, what elements the editor supports, and which document format to use.
• tools (array): Tool definitions the AI or developer can call. Each array element contains:
  • name (string): Tool name.
  • description (string): Tool description.
  • inputSchema (object): JSON schema for the AI-generated tool input.

Example:

curl --location 'BASE_URL/v4/ai/toolkit/fetch-tools' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "editorContext": { /* editor context data */ },
    "tools": {
      "tiptapRead": true,
      "tiptapEdit": {
        "meta": "Briefly explain the edit."
      }
    },
    "format": "shorthandV2"
  }'

Error responses

HTTP errors return:

• error (object): An object with these properties:
  • message (string): Human-readable error message.
  • status (number): HTTP status code.
  • code (string): Stable error code.
  • data (object, optional): Sanitized structured context.

This endpoint can return:

• 401 with access_control_auth_required or missing_token: The request did not include a Tiptap Access Control JWT.
• 401 with an access-control code such as token_expired or signature_invalid: The JWT was rejected by Access Control.
• 403 with feature_not_available: Server AI Toolkit is not enabled for the environment.
• 403 with insufficient_permissions: The JWT does not grant AI:Toolkit.
• 403 with origin_not_allowed: The request Origin is not allowed for the environment.
• 422 with validation_failed: The request body does not match the endpoint schema. The response includes error.issues, a list of validation issues.
• 422 with tool_config_validation_failed: The tool config provided in the request body is invalid. The response includes error.data.issues, a list of validation issues.
• 429 with rate_limited: Access Control rate-limited authentication.
• 429: The server-side rate limiter blocked the request. This response uses a different top-level shape:
  • error (string): Rate limit error message.
  • retryAfter (number, optional): Seconds to wait before retrying.
  • limit (number, optional): Request limit for the current window.
  • window (number, optional): Rate-limit window in seconds.
• 500 with internal_server_error: An unexpected server error occurred.
• 500 with missing_cloud_api_token: The cloud service is missing internal authentication configuration.
• 503 with service_unavailable: Access Control was temporarily unavailable.

Execute a tool

POST /v4/ai/toolkit/execute-tool

Executes a tool. Use this endpoint after the AI model has generated the tool call.

Request body:

• editorContext (object, required): The editor context returned by getEditorContext.
• document (object, required): Document to execute the tool against. Use { "type": "cloud", "id": "your-document-id" } when the API should read from and write to a Tiptap Cloud document. Use { "type": "inline", "content": { /* Tiptap JSON document */ } } when you want to provide the Tiptap JSON document in the request body.
• user (string, optional): Author of the edits in version history. It also sets the user associated with AI-generated comments, threads and Tracked Changes suggestions. use reviewOptions.trackedChangesOptions.userId.
• field (string, optional, default: "default"): Collaborative field to target inside a cloud document. Use this when a document stores multiple editable fields, such as a title and body.
• tool (object, required): Tool call to execute.
  • name (string, required): Tool name, for example "tiptapRead".
  • input (object, required): Tool input generated by the AI. This is an object that matches the schema and the tool definition for that tool. The schemas and tool definitions of each tool are obtained from the /v4/ai/toolkit/fetch-tools endpoint.
  • config (unknown, optional): Tool-specific configuration provided by the developer.
• format ('json' | 'shorthand' | 'shorthandV2', optional, default: 'json'): Document format for tool input and output. See Tiptap Shorthand.
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): Controls whether edits are applied directly or as reviewable changes.

Response:

• tool (object): Executed tool and its output.
  • name (string): Tool name.
  • output (object): Tool output for the AI.
• docChanged (boolean): Whether the document changed.
• before (JSONContent): The Tiptap JSON document before the tool was executed.
• document (JSONContent | null): The Tiptap JSON document after the tool was executed, or null when the document did not change. Changes may involve modifications in document content and also modifications in the _hash attributes of the nodes, which are used as unique identifiers and allow the AI to select the nodes of the document.

Example:

curl --location 'BASE_URL/v4/ai/toolkit/execute-tool' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --data '{
    "editorContext": { /* editor context data */ },
    "document": {
      "type": "cloud",
      "id": "your-document-id"
    },
    "user": "ai-assistant",
    "tool": {
      "name": "tiptapRead",
      "input": {
        "from": 0
      }
    },
    "format": "shorthandV2"
  }'

Error responses

HTTP errors return:

• error (object): An object with these properties:
  • message (string): Human-readable error message.
  • status (number): HTTP status code.
  • code (string): Stable error code.
  • data (object, optional): Sanitized structured context. Document and thread upstream failures include fields such as operation, upstreamStatus, upstreamUrl, and upstreamMethod.

This endpoint can return:

• 400 with missing_document_credentials: The request uses a cloud document, but the JWT does not include document server credentials.
• 400 with missing_document_options: getThreads or editThreads was executed against an inline document. These tools require a cloud document.
• 400 with a thread-store code such as thread_not_found or comment_not_found: A thread or comment operation referenced data that does not exist.
• 401 with access_control_auth_required or missing_token: The request did not include a Tiptap Access Control JWT.
• 401 with an access-control code such as token_expired or signature_invalid: The JWT was rejected by Access Control.
• 403 with feature_not_available: Server AI Toolkit is not enabled for the environment.
• 403 with insufficient_permissions: The JWT does not grant AI:Toolkit, or it does not grant access to the requested cloud document.
• 403 with origin_not_allowed: The request Origin is not allowed for the environment.
• 403 with unsupported_tool_format: The selected tool does not support the requested format.
• 403 with tracked_changes_unsupported_schema: reviewOptions.mode is trackedChanges, but the editor schema does not support tracked changes.
• 403 with thread_schema_not_supported: The editor schema does not support comments or threads.
• 403 with board_schema_not_supported: A board tool got a document or an editor schema that isn't a whiteboard it can work on.
• 409 with concurrent_edit_conflict: The cloud document changed while the tool was executing. Retry the request with the latest document state.
• 422 with validation_failed: The request body does not match the endpoint schema. The response includes error.issues, a list of validation issues.
• 429 with rate_limited: Access Control rate-limited authentication.
• 429: The server-side rate limiter blocked the request. This response uses a different top-level shape:
  • error (string): Rate limit error message.
  • retryAfter (number, optional): Seconds to wait before retrying.
  • limit (number, optional): Request limit for the current window.
  • window (number, optional): Rate-limit window in seconds.
• 500 with document_save_failed: The server could not save the cloud document after loading it, or the save flow was called before a document was loaded.
• 500 with diff_worker_failed or diff_worker_invalid_result: The internal diff worker failed while preparing reviewable changes.
• 500 with internal_server_error or unknown_error: An unexpected server error occurred.
• 500 with missing_cloud_api_token: The cloud service is missing internal authentication configuration.
• 502 with document_load_failed or document_save_failed: Loading or saving the cloud document failed upstream. Check error.data.upstreamStatus for the upstream HTTP status.
• 502 with a thread or comment code such as thread_list_failed, thread_create_failed, thread_update_failed, thread_delete_failed, thread_resolve_failed, thread_unresolve_failed, comment_create_failed, comment_update_failed, or comment_delete_failed: A comments API operation failed upstream.
• 503 with diff_worker_queue_timeout: The diff worker queue was saturated or timed out.
• 503 with service_unavailable: Access Control was temporarily unavailable.

Stream a tool

POST /v4/ai/toolkit/stream-tool

Streams tool execution. tiptapEdit can apply edits incrementally for a typing effect. Other tools run after the full input is received and return one final event, like execute-tool.

The request is sent in parts. The first part contains:

• editorContext (object, required): The editor context returned by getEditorContext.
• document (object, required): Cloud document to stream the edit into: { "type": "cloud", "id": "your-document-id" }. Inline documents are not supported for streaming.
• user (string, optional): Author of the edits in version history, comments and threads (for example with editThreads). It does not set the author of Tracked Changes suggestions, for Tracked Changes authorship use reviewOptions.trackedChangesOptions.userId.
• field (string, optional, default: "default"): Collaborative field to target inside a cloud document. Streaming supports only the default field; any other value is rejected.
• tool (object, required): Tool call to execute, without tool.input.
  • name (string, required): Tool name, for example "tiptapEdit".
  • config (unknown, optional): Tool-specific configuration provided by the developer.
• format ('json' | 'shorthand' | 'shorthandV2', optional, default: 'json'): Document format for tool input and output. See Tiptap Shorthand.
• reviewOptions (ReviewOptions, optional, default: { mode: 'disabled' }): Controls whether edits are applied directly or as reviewable changes.
• delayMs (number, optional, default: 5): Per-character delay in milliseconds for incremental tiptapEdit output. Must be between 0 and 1000. Use 0 to apply edits as fast as possible.

Then send:

• Following parts: The value of tool.input, streamed as the AI generates it.

Response:

• tiptapEdit: Incremental events while edits are applied, followed by a final event with the updated document.
• Other tools: One final event with the same result shape as execute-tool.

Error responses

Before streaming starts, HTTP errors use the same JSON shape as execute-tool:

• error (object): An object with these properties:
  • message (string): Human-readable error message.
  • status (number): HTTP status code.
  • code (string): Stable error code.
  • data (object, optional): Sanitized structured context.

After streaming starts, errors are sent as NDJSON events:

• version (number): Stream protocol version.
• type ('error'): Event type.
• code (string): Stable error code.
• status (number): HTTP-style status code.
• message (string): Human-readable error message.

This endpoint can return or emit:

• 400 with invalid_request: The request has no body.
• 400 with missing_document_credentials: The JWT does not include document server credentials.
• 400 with invalid_stream_message: A stream message is not valid JSON, fails schema validation, uses an unsupported protocol version, or the stream ends with an unterminated NDJSON line.
• 400 with duplicate_start: More than one start message was sent.
• 400 with delta_before_start: A delta message arrived before start.
• 400 with end_before_start: An end message arrived before start.
• 400 with incomplete_stream: The request ended before an end message arrived.
• 400 with a thread-store code such as thread_not_found or comment_not_found: A buffered thread or comment operation referenced data that does not exist.
• 401 with access_control_auth_required or missing_token: The request did not include a Tiptap Access Control JWT.
• 401 with an access-control code such as token_expired or signature_invalid: The JWT was rejected by Access Control.
• 403 with feature_not_available: Server AI Toolkit is not enabled for the environment.
• 403 with insufficient_permissions: The JWT does not grant AI:Toolkit.
• 403 with origin_not_allowed: The request Origin is not allowed for the environment.
• 403 with tracked_changes_unsupported_schema: reviewOptions.mode is trackedChanges, but the editor schema does not support tracked changes.
• 403 with thread_schema_not_supported: The editor schema does not support comments or threads.
• 413 with ndjson_line_too_long: A single NDJSON line exceeded the maximum size.
• 429 with stream_rate_limit_exceeded: Too many concurrent streams are open for the same client.
• 429 with rate_limited: Access Control rate-limited authentication.
• 429: The server-side rate limiter blocked the request before streaming started. This response uses a different top-level shape:
  • error (string): Rate limit error message.
  • retryAfter (number, optional): Seconds to wait before retrying.
  • limit (number, optional): Request limit for the current window.
  • window (number, optional): Rate-limit window in seconds.
• 500 with diff_worker_failed, diff_worker_invalid_result, stream_internal_error, or unknown_error: An unexpected server error occurred during stream processing.
• 500 with missing_cloud_api_token: The cloud service is missing internal authentication configuration.
• 502 with document, thread, or comment upstream failure codes such as document_load_failed, document_save_failed, thread_list_failed, or comment_create_failed: A cloud document or comments API operation failed upstream.
• 503 with diff_worker_queue_timeout: The diff worker queue was saturated or timed out.
• 503 with service_unavailable: Access Control was temporarily unavailable.
• 504 with stream_request_timeout: The stream exceeded the server request timeout.

Available tools

These tools can be provided to an AI agent. The agent decides which tool to call.

All tools are disabled by default. We recommend starting with tiptapRead and tiptapEdit, then enabling additional tools as needed.

You can also call these tools directly from your application code to build custom workflows.

tiptapRead

Reads the document in chunks to avoid overflowing the context window.

Tool input (tool.input):

• from (number, required): Zero-based index of the first top-level node to read. Must be a non-negative integer.

Tool config (tool.config):

• chunkSize (number, optional): Maximum number of characters to read in each tool call. Default: 32000

Tool output (tool.output):

Success response:

• success (true): Indicates that the read request was successful.
• totalNodeCount (number): Total number of top-level nodes in the document.
• nodeRange ([number, number]): Top-level node range that was read.
• content (JSONContent[] | string): Document content for the returned range. When format is json, this is a Tiptap JSON fragment. When format is shorthand or shorthandV2, this is a Tiptap Shorthand string.

Error response:

• success (false): Indicates that the read request failed.
• error (string): Error message.
• totalNodeCount? (number): Total number of top-level nodes.

tiptapEdit

Edits document content.

Tool input (tool.input):

• operations (array, required): One or more edit operations, applied sequentially.
  • type ('replace' | 'insertBefore' | 'insertAfter', required): Edit to perform.
  • target (string, required): Selects a node of the document where the operation will be applied, or the entire document. It is the value of the _hash attribute of the selected node, or "doc" to target the entire document.
  • content (JSONContent[] | string, required): Replacement or inserted content. Use a Tiptap JSON fragment when format is json, or a Tiptap Shorthand string when format is shorthand or shorthandV2. To delete a node, use an empty fragment.
  • meta (string, optional): Metadata for the operation. This field is required when the tiptapEdit.meta option passed to fetch-tools is set.

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Whether all operations completed successfully.
• operationResults (array): Result for each operation.
  • success (boolean): Whether the operation completed successfully.
  • target (string): String identifier of the element targeted by the operation.
  • error (string | null): Failure reason, or null if the operation succeeded.

Error response:

• success (false): Indicates that the edit request failed.
• reason ('validationError' | 'unexpectedError'): Error category.
• error (string): Error message.

tiptapQuery

Reads, searches and edits the document with JSON operations. It works on its own, without tiptapRead or tiptapEdit. It is not available through stream-tool.

Tool input (tool.input):

• operations (array, required): 1 to 50 operations, run in order. Each operation selects content and reads or edits it. See the tiptapQuery reference for the operation format.

Tool config (tool.config):

• chunkSize (number, optional): Maximum number of characters that all reads of one tool call return together. Default: 32000
• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

• success (boolean): Whether all operations completed successfully.
• operationResults (array): Result for each operation that ran. See the tiptapQuery reference.
• skipped (number): Number of operations that didn't run because an earlier operation failed.

replaceDocument

Replaces the entire document with new content.

Tool input (tool.input):

• content (JSONContent | string, required): The replacement document content. Use a Tiptap JSON document when format is json, or a Tiptap Shorthand string when format is shorthand or shorthandV2.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that the document was replaced successfully.

Error response:

• success (false): Indicates that the document could not be replaced.
• error (string): Error message.

createDocument

Alias for replaceDocument. It accepts the same input and returns the same output.

readSelection

Reads the user's current editor selection.

This tool is only compatible with Tiptap Cloud collaborative documents. In multi-field documents, only the default field is supported.

Tool input (tool.input):

This tool does not take any input. Pass an empty object ({}).

Tool config (tool.config):

• user (string, required): The ID of the user whose selection to read. Must be the same as the user.id defined in the Collaboration Caret extension.

Tool output (tool.output):

Success response:

• success (true): Indicates that the request succeeded.
• isEmpty (false): A non-empty selection was resolved.
• content (JSONContent[] | string): The nodes of the document that contain the selection, with special markers delimiting the selection.
• nodeRange ([number, number]): The node range where the selection is located.

Success response (empty selection):

• success (true): Indicates that the request succeeded.
• isEmpty (true): The selection is empty

getThreads

Reads comment threads from a cloud document.

Tool input (tool.input):

• from (number, required): Zero-based index of the first thread to read. Must be a non-negative integer.

Tool config (tool.config):

• chunkSize (number, optional): Maximum number of characters to read in each tool call. Default: 32000

Tool output (tool.output):

Success response:

• success (true): Indicates that the read request was successful.
• totalThreadCount (number): Total number of threads in the document.
• threadRange ([number, number]): Thread range that was read, as [from, to).
• threads (array): Returned thread objects.
  • id (string): Unique thread identifier.
  • nodeRange ([number, number] | null): Node range where the thread is located, or null if the thread is not annotated in the document.
  • content (JSONContent[] | string | null): Content marked by the thread. When format is json, this is a Tiptap JSON fragment. When format is shorthand or shorthandV2, this is a Tiptap Shorthand string. null means the thread is not annotated in the document.
  • comments (array): Comments in the thread.
    • id (string): Unique comment identifier.
    • content (string): Comment text.
    • userId (string): ID of the user who created the comment.
    • createdAt (string): ISO timestamp when the comment was created.
    • updatedAt (string): ISO timestamp when the comment was last updated.
  • resolvedAt? (string | null): ISO timestamp when the thread was resolved, or null if unresolved.
  • createdAt (string): ISO timestamp when the thread was created.
  • updatedAt (string): ISO timestamp when the thread was last updated.
  • data? (Record<string, unknown>): Public thread metadata.

Error response:

• success (false): Indicates that the read request failed.
• error (string): Error message.
• totalThreadCount? (number): Total number of persisted threads, when known.

editThreads

Creates and updates comment threads.

Tool input (tool.input):

• operations (array, required): One or more thread operations, applied sequentially. Each operation has one of these shapes:
  • createThread: type ('createThread', required), nodeHash (string, required), and content (JSONContent[] | string, required). content is the node content with inlineThread marks added, as a Tiptap JSON fragment when format is json or a Tiptap Shorthand string when format is shorthand or shorthandV2.
  • createComment: type ('createComment', required), threadId (string, required), and content (string, required).
  • updateComment: type ('updateComment', required), threadId (string, required), commentId (string, required), and content (string, required).
  • removeComment: type ('removeComment', required), threadId (string, required), and commentId (string, required).
  • removeThread: type ('removeThread', required) and threadId (string, required).
  • resolveThread: type ('resolveThread', required) and threadId (string, required).
  • unresolveThread: type ('unresolveThread', required) and threadId (string, required).

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Indicates whether all operations completed successfully.
• operations (array): Result for each operation.
  • type (string): Operation type that was executed.
  • success (boolean): Whether the operation completed successfully.
  • message (string): Human-readable operation result.
  • threadId? (string): Thread ID for operations that create or reference a thread.

Error response:

• success (false): Indicates that the request failed before operations were processed.
• error (string): Error message.

readDocument

Reads the entire document.

Tool input (tool.input):

This tool does not take any input. Pass an empty object ({}).

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that the document was read successfully.
• content (JSONContent[] | string): Whole effective document content. When format is json, this is a Tiptap JSON fragment. When format is shorthand or shorthandV2, this is a Tiptap Shorthand string.

proofread

Applies proofreading edits.

This tool supports format: "shorthand" and format: "shorthandV2".

Tool input (tool.input):

• operations (array, required): One or more proofreading operations, applied sequentially.
  • target (string, required): Selects a node of the document where the operation will be applied, or the entire document. It is the value of the _hash attribute of the selected node, or "doc" to target the entire document.
  • delete (string, required): Exact text to remove. Only its first occurrence in the target node is replaced.
  • insert (string, required): Corrected text to insert in place of delete.
  • meta (string, optional): Metadata for the operation. This field is required when the proofread.meta option passed to fetch-tools is set.

Tool config (tool.config):

• threadData (object, optional): Metadata added to created threads.
• commentData (object, optional): Metadata added to created comments.

Tool output (tool.output):

Success or partial-success response:

• success (boolean): Indicates whether all operations completed successfully.
• operationResults (array): Result for each operation.
  • target (string): String identifier of the element targeted by the operation.
  • success (boolean): Whether the operation completed successfully.
  • error (string | null): Failure reason, or null when the operation succeeded.

Board tools

These tools read and change a whiteboard. Execute them with the editor context of the board's editor, on the board's document. See Use with Whiteboard for the setup.

The board tools take plain text, not document content, so they work the same in every format. They aren't available through stream-tool.

A board tool that can't run changes nothing. When the model can fix the call, like an input that doesn't match the schema or ids that aren't on the board, the tool answers with HTTP status 200, and with success: false and an error in its tool output.

When the request itself can't work, execute-tool fails like it does for the other tools:

• 403 with board_schema_not_supported: The document or the editor context isn't a whiteboard that the tool can work on, like a board without doc frames for createDocFrame.
• 403 with tracked_changes_unsupported_schema: reviewOptions.mode is 'trackedChanges' for a tool that changes the board, but the editor context has no Tracked Changes. readBoard doesn't check this.

Board tool config

readBoard, createShapes, createDiagram and createDocFrame take this tool config (tool.config):

• selectedIds (string[], optional): Ids of the shapes that the user selects, in the order of the selection.
• viewport ({ x: number, y: number, width: number, height: number }, optional): The part of the board that the user sees, in board units. width and height must be above 0.

Each field that is missing, null or invalid falls back on its own: to no selection, or to no viewport.

Board placement

createShapes, createDiagram and createDocFrame take these fields in their input (tool.input), so the AI can name the place for new content:

• near (string[], optional): Up to 100 ids of the shapes that the new content belongs next to, like the diagram that a summary is about. Defaults to the selected shapes.
• side ('right' | 'below' | 'left' | 'above', optional): The side of those shapes for the new content. Defaults to 'right', or 'below' when the free spot there is closer.

New shapes go beside the shapes in near that are on the board, or else beside the selected shapes. Without such shapes, they go in the middle of the viewport, or else right of all shapes on the board, or at the origin of an empty board. When other shapes are in the way, they move to the closest free spot.

Board suggestions

With reviewOptions.mode: 'trackedChanges', the board tools write their changes as suggestions of Tracked Changes:

• The shapes that one call adds or deletes share one suggestion, so one acceptSuggestion or rejectSuggestion reviews them all.
• Each changed shape and each new text get a suggestion of their own. A later change of a shape that waits for a review of the same user goes into that suggestion.
• The tools leave a shape alone that waits for another user's review, or for a review that deletes it, and don't delete a shape that waits for a review of a change. They say why in skipped or skippedArrows.

suggestionIds (string[]) lists the suggestions that the call made or went on with. A suggestion that the call went on with also holds the earlier change, and a change to a shape that an earlier suggestion adds is part of that add, so it isn't listed. Other suggestions stay as they are when you review these ids. Without review, suggestionIds is empty, and the tools leave every shape alone that waits for a review.

readBoard

Reads the shapes of the board, the arrows between them and the selection. It doesn't change the document.

Tool input (tool.input):

This tool does not take any input. Pass an empty object ({}).

Tool config (tool.config):

The board tool config.

Tool output (tool.output):

Success response:

• success (true): Indicates that the board was read.
• shapeCount (number): Number of shapes on the board, arrows included.
• selectedIds (string[]): Ids of the selected shapes that are on the board.
• shapes (array): The shapes, selected ones first.
  • id (string): Unique shape identifier.
  • type (string): Node type, like stickyNote, geo, freeText, freehand or docFrame.
  • kind? (string): Kind of a geometric shape, like rectangle or diamond.
  • x, y, width, height (number): Box of the shape, in whole board units. y grows downwards.
  • color? (string): Color name, like yellow.
  • text? (string): Text of the shape, one line per paragraph or list item. List items start with - , 1. , [ ] or [x] . The text of shapes that aren't selected is cut after 280 characters.
  • docId? (string): Id of the document that a doc frame shows. Every doc frame has it. For a frame without a docId attribute, it is the shape id, whose document the frame shows.
  • selected? (true): The user selects the shape.
  • suggestion? ('add' | 'delete' | 'change'): A suggestion that waits for a review, and adds or deletes the shape, or changes its attributes or its text.
• arrows (array): The arrows on the board.
  • id (string): Unique arrow identifier.
  • fromId (string | null): Id of the shape where the arrow starts, or null for a free end.
  • toId (string | null): Id of the shape that the arrow points to, or null for a free end.
• omittedShapeCount (number): Number of shapes and arrows that the output leaves out. It lists at most 300.
• viewport (object | null): The viewport of the tool config.

createShapes

Adds sticky notes as one grid, in front of all shapes.

Tool input (tool.input):

• notes (array, required): 1 to 24 notes, in reading order.
  • text (string, required): Text of the note, up to 500 characters. A line break starts a new paragraph. Lines that start with - , 1. , [ ] or [x] make a bulleted list, a numbered list or a task list.
  • color ('black' | 'gray' | 'red' | 'orange' | 'yellow' | 'green' | 'blue' | 'violet', optional): Color of the note. Default: 'yellow'
• near and side (optional): Where the notes go. See board placement.

Tool config (tool.config):

The board tool config.

Tool output (tool.output):

Success response:

• success (true): Indicates that the notes were added.
• createdIds (string[]): Ids of the new notes, in the order of the input.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no notes were added.
• error (string): Error message.

arrangeShapes

Groups shapes into columns from left to right, each with a free text title on top. The columns start where the shapes are, or at the closest free spot when they would cover other shapes. Shapes only move, so the arrows that connect them follow.

Tool input (tool.input):

• groups (array, required): 1 to 12 groups, from left to right, with at most 300 ids in all.
  • title (string, required): Title of the group, up to 60 characters.
  • ids (string[], required): Ids of the shapes in the group, in reading order. A shape joins the first group that names it.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that the shapes were arranged.
• movedIds (string[]): Ids of the shapes that moved.
• titleIds (string[]): Ids of the new titles.
• skipped (array): Shapes that stayed where they were, each with id and reason, like an id that isn't a shape on the board, an arrow, an id that an earlier group names, or a shape that waits for another user's review.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no shapes were arranged. The error lists the reasons.
• error (string): Error message.

createDiagram

Draws shapes with text, connected by arrows, and lays them out as a diagram. The arrows connect the shapes, so they follow when a user moves a shape.

Tool input (tool.input):

• title (string, optional): Title above the diagram, up to 80 characters.
• direction ('down' | 'right', optional): Where the arrows mostly point. Default: 'down'
• nodes (array, required): 1 to 40 shapes.
  • key (string, required): The AI's own name for the shape, up to 40 characters and unique in the diagram. Arrows refer to it.
  • text (string, required): Text in the shape, up to 60 characters.
  • shape ('rectangle' | 'ellipse' | 'diamond', optional): Kind of the shape. Another kind becomes a rectangle. Default: 'rectangle'
  • color (string, optional): One of the colors of createShapes. Default: 'black'
• arrows (array, optional): Up to 60 arrows.
  • from (string, required): Key of the shape where the arrow starts.
  • to (string, required): Key of the shape that the arrow points to.
  • label (string, optional): Label beside the arrow, up to 24 characters.
• near and side (optional): Where the diagram goes. See board placement.

Tool config (tool.config):

The board tool config.

Tool output (tool.output):

Success response:

• success (true): Indicates that the diagram was drawn.
• createdIds (string[]): Ids of all new shapes: the title, the shapes, the arrows and their labels.
• nodeIds (Record<string, string>): Id of each new shape, by its key.
• skippedArrows (array): Arrows that were left out, each with from, to and reason. An arrow with an unknown key, from a shape to itself, or that came earlier is left out.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that the diagram was not drawn.
• error (string): Error message.

updateShapes

Changes the text, color or kind of shapes. Shapes keep their place and size.

Tool input (tool.input):

• shapes (array, required): 1 to 40 shapes, each shape once, with only what changes.
  • id (string, required): Id of the shape.
  • text (string, optional): New text, up to 500 characters, with the same lines as for createShapes. It replaces the text of the shape, without its formatting. The text that readBoard gives for the shape is no change. Only sticky notes, geometric shapes and free text have text.
  • color (string, optional): New color, one of the colors of createShapes.
  • kind ('rectangle' | 'ellipse' | 'diamond' | 'triangle', optional): New kind of a geometric shape.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that at least one shape changed.
• updatedIds (string[]): Ids of the changed shapes.
• skipped (array): Shapes that stayed as they were, each with id and reason, like a shape that waits for another user's review, or a shape without text that gets a text.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no shape changed. The error lists the reasons.
• error (string): Error message.

deleteShapes

Deletes shapes, arrows included. Arrows that connected a deleted shape keep a free end.

Tool input (tool.input):

• ids (string[], required): 1 to 100 ids of shapes.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that the shapes were deleted. With review, they stay with a delete suggestion until a user accepts it.
• deletedIds (string[]): Ids of the deleted shapes.
• skipped (array): Shapes that stayed on the board, each with id and reason, like an id that isn't a shape on the board, or a shape that waits for a review.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no shapes were deleted. The error lists the reasons.
• error (string): Error message.

connectShapes

Draws arrows between shapes that are on the board, each with an optional label beside it.

Tool input (tool.input):

• arrows (array, required): 1 to 40 arrows.
  • from (string, required): Id of the shape where the arrow starts.
  • to (string, required): Id of the shape that the arrow points to.
  • label (string, optional): Label beside the arrow, up to 24 characters.

Tool config (tool.config):

null

Tool output (tool.output):

Success response:

• success (true): Indicates that at least one arrow was drawn.
• createdIds (string[]): Ids of the new arrows and labels.
• skippedArrows (array): Arrows that were left out, each with from, to and reason: an unknown shape, an arrow from a shape to itself, a shape that waits to be deleted, or an arrow that the board has already.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no arrow was drawn. The error lists the reasons.
• error (string): Error message.

createDocFrame

Adds a doc frame with a new, empty document, in front of all shapes. Write the document with tiptapEdit, on the Tiptap Cloud document of its docId. See Write the documents of doc frames.

Tool input (tool.input):

• lines (number, optional): About how many lines the document will have, as a whole number from 1 to 400. The frame keeps room for them. Default: 12
• near and side (optional): Where the frame goes. See board placement.

Tool config (tool.config):

The board tool config.

Tool output (tool.output):

Success response:

• success (true): Indicates that the frame was added.
• frameId (string): Id of the new frame.
• docId (string): Id of the frame's document.
• suggestionIds (string[]): See board suggestions.

Error response:

• success (false): Indicates that no frame was added.
• error (string): Error message.

Related pages

• Review options
• Editor context