Class PlotAbstract

constructor

• new Plot(): Plot

  Returns Plot

AbstractcreateThread

• createThread(thread: NewThread | NewThreadWithNotes): Promise<Uuid>

  Creates a new thread in the Plot system.

  The thread will be automatically assigned an ID and author information based on the current execution context. All other fields from NewThread will be preserved in the created thread.

  Parameters

  • thread: NewThread | NewThreadWithNotes

    The thread data to create

  Returns Promise<Uuid>

  Promise resolving to the created thread's ID

AbstractcreateThreads

• createThreads(threads: (NewThread | NewThreadWithNotes)[]): Promise<Uuid[]>

  Creates multiple threads in a single batch operation.

  This method efficiently creates multiple threads at once, which is more performant than calling createThread() multiple times individually. All threads are created with the same author and access control rules.

  Parameters

  • threads: (NewThread | NewThreadWithNotes)[]

    Array of thread data to create

  Returns Promise<Uuid[]>

  Promise resolving to array of created thread IDs

AbstractupdateThread

• updateThread(thread: ThreadUpdate): Promise<void>

  Updates an existing thread in the Plot system.

  Important: This method only updates existing threads. It will throw an error if the thread does not exist. Use createThread() to create or update (upsert) threads.

  Only the fields provided in the update object will be modified - all other fields remain unchanged. This enables partial updates without needing to fetch and resend the entire thread object.

  For tags, provide a Record<number, boolean> where true adds a tag and false removes it. Tags not included in the update remain unchanged.

  When updating the parent, the thread's path will be automatically recalculated to maintain the correct hierarchical structure.

  Scheduling is handled separately via createSchedule() / updateSchedule().

  Parameters

  • thread: ThreadUpdate

    The thread update containing the ID or source and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

  Throws

  Error if the thread does not exist

  Example

  // Mark a task as complete
  await this.plot.updateThread({
    id: "task-123",
    done: new Date()
  });
  
  // Add and remove tags
  await this.plot.updateThread({
    id: "thread-789",
    tags: {
      1: true,  // Add tag with ID 1
      2: false  // Remove tag with ID 2
    }
  });
  Copy

AbstractgetNotes

• getNotes(thread: ThreadFields): Promise<Note[]>

  Retrieves all notes within a thread.

  Notes are detailed entries within a thread, ordered by creation time. Each note can contain markdown content, actions, and other detailed information related to the parent thread.

  Parameters

  • thread: ThreadFields

    The thread whose notes to retrieve

  Returns Promise<Note[]>

  Promise resolving to array of notes in the thread

AbstractcreateNote

• createNote(note: NewNote): Promise<Uuid>

  Creates a new note in a thread.

  Notes provide detailed content within a thread, supporting markdown, actions, and other rich content. The note will be automatically assigned an ID and author information based on the current execution context.

  Parameters

  • note: NewNote

    The note data to create

  Returns Promise<Uuid>

  Promise resolving to the created note's ID

  Example

  // Create a note with content
  await this.plot.createNote({
    thread: { id: "thread-123" },
    note: "Discussion notes from the meeting...",
    contentType: "markdown"
  });
  
  // Create a note with actions
  await this.plot.createNote({
    thread: { id: "thread-456" },
    note: "Meeting recording available",
    actions: [{
      type: ActionType.external,
      title: "View Recording",
      url: "https://example.com/recording"
    }]
  });
  Copy

AbstractcreateNotes

• createNotes(notes: NewNote[]): Promise<Uuid[]>

  Creates multiple notes in a single batch operation.

  This method efficiently creates multiple notes at once, which is more performant than calling createNote() multiple times individually. All notes are created with the same author and access control rules.

  Parameters

  • notes: NewNote[]

    Array of note data to create

  Returns Promise<Uuid[]>

  Promise resolving to array of created note IDs

  Example

  // Create multiple notes in one batch
  await this.plot.createNotes([
    {
      thread: { id: "thread-123" },
      note: "First message in thread"
    },
    {
      thread: { id: "thread-123" },
      note: "Second message in thread"
    }
  ]);
  Copy

AbstractupdateNote

• updateNote(note: NoteUpdate): Promise<void>

  Updates an existing note in the Plot system.

  Important: This method only updates existing notes. It will throw an error if the note does not exist. Use createNote() to create or update (upsert) notes.

  Only the fields provided in the update object will be modified - all other fields remain unchanged. This enables partial updates without needing to fetch and resend the entire note object.

  Parameters

  • note: NoteUpdate

    The note update containing the ID or key and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

  Throws

  Error if the note does not exist

  Example

  // Update note content
  await this.plot.updateNote({
    id: "note-123",
    note: "Updated content with more details"
  });
  
  // Add tags to a note
  await this.plot.updateNote({
    id: "note-456",
    twistTags: {
      [Tag.Important]: true
    }
  });
  Copy

AbstractgetThread

• getThread(
      thread: { id: Uuid } | { source: string },
  ): Promise<ThreadFields | null>

  Retrieves a thread by ID or source.

  This method enables lookup of threads either by their unique ID or by their source identifier (canonical URL from an external system). Archived threads are included in the results.

  Parameters

  • thread: { id: Uuid } | { source: string }

    Thread lookup by ID or source

  Returns Promise<ThreadFields | null>

  Promise resolving to the matching thread or null if not found

AbstractgetNote

• getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>

  Retrieves a note by ID or key.

  This method enables lookup of notes either by their unique ID or by their key (unique identifier within the thread). Archived notes are included in the results.

  Parameters

  • note: { id: Uuid } | { key: string }

    Note lookup by ID or key

  Returns Promise<Note | null>

  Promise resolving to the matching note or null if not found

AbstractcreatePriority

• createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>

  Creates a new priority in the Plot system.

  Priorities serve as organizational containers for threads and twists. The created priority will be automatically assigned a unique ID.

  Parameters

  • priority: NewPriority

    The priority data to create

  Returns Promise<Priority & { created: boolean }>

  Promise resolving to the complete created priority

AbstractgetPriority

• getPriority(priority: { id: Uuid } | { key: string }): Promise<Priority | null>

  Retrieves a priority by ID or key.

  Archived priorities are included in the results.

  Parameters

  • priority: { id: Uuid } | { key: string }

    Priority lookup by ID or key

  Returns Promise<Priority | null>

  Promise resolving to the matching priority or null if not found

AbstractupdatePriority

• updatePriority(update: PriorityUpdate): Promise<void>

  Updates an existing priority in the Plot system.

  The priority is identified by either its ID or key. Only the fields specified in the update will be changed.

  Parameters

  • update: PriorityUpdate

    Priority update containing ID/key and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

AbstractgetActors

• getActors(ids: ActorId[]): Promise<Actor[]>

  Retrieves actors by their IDs.

  Actors represent users, contacts, or twists in the Plot system. This method requires ContactAccess.Read permission.

  Parameters

  • ids: ActorId[]

    Array of actor IDs to retrieve

  Returns Promise<Actor[]>

  Promise resolving to array of actors

AbstractgetOwner

• getOwner(): Promise<Actor>

  Returns the full Actor for the user who installed this twist. Useful for per-user operations like schedule creation, or when the owner's name or email is needed.

  Returns Promise<Actor>

AbstractgetUserId

• getUserId(): Promise<string>

  Returns the user ID (twist_instance.owner_id) that installed this twist. This is the same value exposed on Twist via this.userId.

  Returns Promise<string>

AbstractgetDefaultPriorityId

• getDefaultPriorityId(): Promise<string>

  Returns the owner user's root priority ID. Used as the implicit default when an operation needs a priority but the caller didn't supply one — for example, plot.createPriority() without a parent, or plot.getThreads() without an explicit priorityId.

  On the server, priority resolution for newly created threads/links happens automatically via match_priority_for_user; twists rarely need to call this directly.

  Returns Promise<string>

AbstractcreateSchedule

• createSchedule(schedule: NewSchedule): Promise<Schedule>

  Creates a new schedule for a thread.

  Schedules define when a thread occurs in time. A thread can have multiple schedules (shared and per-user).

  Parameters

  • schedule: NewSchedule

    The schedule data to create

  Returns Promise<Schedule>

  Promise resolving to the created schedule

  Example

  // Schedule a timed event
  const threadId = await this.plot.createThread({
    title: "Team standup"
  });
  await this.plot.createSchedule({
    threadId,
    start: new Date("2025-01-15T10:00:00Z"),
    end: new Date("2025-01-15T10:30:00Z"),
    recurrenceRule: "FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"
  });
  Copy

AbstractgetSchedules

• getSchedules(threadId: Uuid): Promise<Schedule[]>

  Retrieves all schedules for a thread.

  Parameters

  • threadId: Uuid

    The thread whose schedules to retrieve

  Returns Promise<Schedule[]>

  Promise resolving to array of schedules for the thread

AbstractgetLinks

• getLinks(filter?: LinkFilter): Promise<{ link: Link; notes: Note[] }[]>

  Retrieves links from connected source channels.

  Requires link: true in Plot options.

  Parameters

  • Optionalfilter: LinkFilter

    Optional filter criteria for links

  Returns Promise<{ link: Link; notes: Note[] }[]>

  Promise resolving to array of links with their notes

Abstractsearch

• search(query: string, options?: SearchOptions): Promise<SearchResult[]>

  Searches notes and links using semantic similarity.

  Requires search: true in Plot options.

  Parameters

  • query: string

    The search query text

  • Optionaloptions: SearchOptions

    Optional search configuration

  Returns Promise<SearchResult[]>

  Promise resolving to array of search results ordered by similarity

AbstractgetThreads

• getThreads(
      options?: {
          priorityId?: Uuid;
          includeDescendants?: boolean;
          includeArchived?: boolean;
          limit?: number;
          offset?: number;
      },
  ): Promise<ThreadFields[]>

  Lists threads owned by the twist's user.

  Requires ThreadAccess.Full.

  Parameters

  • Optionaloptions: {
        priorityId?: Uuid;
        includeDescendants?: boolean;
        includeArchived?: boolean;
        limit?: number;
        offset?: number;
    }

    Query options for filtering threads

    • OptionalpriorityId?: Uuid

      Priority to list threads from. Must be owned by the twist owner. When omitted, defaults to the owner's root priority.

    • OptionalincludeDescendants?: boolean

      Include threads from descendant priorities. Default: true.

    • OptionalincludeArchived?: boolean

      Include archived threads. Default: false.

    • Optionallimit?: number

      Maximum number of threads to return. Default: 50, max: 200.

    • Optionaloffset?: number

      Number of threads to skip for pagination. Default: 0.

  Returns Promise<ThreadFields[]>

  Promise resolving to array of threads

AbstractgetPriorities

• getPriorities(
      options?: {
          parentId?: Uuid;
          includeDescendants?: boolean;
          includeArchived?: boolean;
      },
  ): Promise<Priority[]>

  Lists priorities owned by the twist's user.

  Requires PriorityAccess.Full.

  Parameters

  • Optionaloptions: { parentId?: Uuid; includeDescendants?: boolean; includeArchived?: boolean }

    Query options for filtering priorities

    • OptionalparentId?: Uuid

      Parent priority to list children of. Must be owned by the twist owner. When omitted, defaults to the owner's root priority.

    • OptionalincludeDescendants?: boolean

      Include all descendants, not just direct children. Default: false.

    • OptionalincludeArchived?: boolean

      Include archived priorities. Default: false.

  Returns Promise<Priority[]>

  Promise resolving to array of priorities

AbstractupdateLink

• updateLink(link: LinkUpdate): Promise<void>

  Updates a link.

  Requires LinkAccess.Full. Set threadId to move the link to a different thread.

  Parameters

  • link: LinkUpdate

    The link update containing the ID and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

AbstractcreatePlan

• createPlan(
      options: {
          title: string;
          operations: PlanOperation[];
          callback: Callback;
      },
  ): Action

  Creates a plan of operations for user approval.

  Returns an Action that can be attached to a note. The user can approve, deny, or request changes. On approval, operations are executed by the API.

  Requires requireApproval: true in Plot options.

  Parameters

  • options: { title: string; operations: PlanOperation[]; callback: Callback }

    Plan configuration

    • title: string

      Human-readable title summarizing the plan

    • operations: PlanOperation[]

      Array of operations to execute on approval

    • callback: Callback

      Callback invoked with (action, approved: boolean) when the user responds

  Returns Action

  An Action of type plan to attach to a note

Static ReadonlyOptions

// Minimal configuration with required permissions
build(build: ToolBuilder) {
  return {
    plot: build(Plot, {
      thread: {
        access: ThreadAccess.Create
      }
    })
  };
}

// Full configuration with callbacks
build(build: ToolBuilder) {
  return {
    plot: build(Plot, {
      thread: {
        access: ThreadAccess.Create,
      },
      note: {
        intents: [{
          description: "Schedule meetings",
          examples: ["Schedule a meeting tomorrow"],
          handler: this.onSchedulingIntent
        }],
      },
      link: true,
      priority: {
        access: PriorityAccess.Full
      },
      contact: {
        access: ContactAccess.Read
      }
    })
  };
}
Copy