Assistant Migration Guide

The Assistants API will be deprecated on 16 August.For new systems, we recommend using the Agents API. The Agents API provides native Vercel AI SDK compatibility and removes custom transformations.See the migration guide to learn about the differences.

This guide explains how to migrate Assistants from one Langdock workspace to another using the Assistant API. This is useful when you want to replicate assistant configurations across different workspaces, move assistants during organizational restructuring, or create backup copies of your assistants.

Overview

The migration process involves two main steps:

Export: Retrieve the Assistant configuration from the source workspace using the assistant Get API
Import: Create a new Assistant in the target workspace using the assistant Create API

Prerequisites

Before you begin, ensure you have:

Two API keys with AGENT_API scope:
- One API key for the source workspace (where the Assistant currently exists)
- One API key for the target workspace (where you want to migrate the Assistant)
Access to the Assistant: Your source workspace API key must have access to the assistant you want to migrate
Matching resources in target workspace (if applicable):
- If the target workspace does not have access to the same model, set model in the script to an available deployment name before migration
- If the Assistant uses custom actions, those integrations must be enabled in the target workspace
- Attachments need to be re-uploaded separately (they are not transferred automatically)

Step 1: Export the Assistant from Source Workspace

Use the Assistant Get API to retrieve the settings available for your assistant:

const axios = require("axios");

async function getAssistantFromSource(assistantId, sourceApiKey) {
  const response = await axios.get(
    "https://api.langdock.com/assistant/v1/get",
    {
      params: {
        assistantId: assistantId
      },
      headers: {
        Authorization: `Bearer ${sourceApiKey}`
      }
    }
  );

  return response.data.assistant;
}

Understanding the Response

The Get API returns the following Assistant settings:

name, description, instruction - The Assistant’s identity and system prompt
emojiIcon - The emoji icon displayed for the Assistant
model - Identifier of the model being used
temperature - Creativity setting (0-1)
conversationStarters - Suggested prompts for users
inputType - The configured input type
inputFields - Display properties for form fields. The response does not include the slug, options, fileTypes, or emailDomain values required to recreate them
webSearchEnabled, imageGenerationEnabled, canvasEnabled - Capability flags
extendedThinking - Whether extended thinking is enabled
actions - Custom integration actions
attachments - UUIDs of attached files
knowledgeFolderIds - UUIDs of connected Folders

canvasEnabled is read-only in these endpoints and is not transferred by this migration.

Step 2: Transform the Configuration

The Get API response uses slightly different field names than the Create API expects. You need to map the fields:

function transformForCreate(sourceAssistant) {
  return {
    // Basic information
    name: sourceAssistant.name,
    description: sourceAssistant.description || undefined,
    emoji: sourceAssistant.emojiIcon || undefined,
    instruction: sourceAssistant.instruction || undefined,
    
    // Settings
    model: sourceAssistant.model,
    creativity: sourceAssistant.temperature,
    inputType: sourceAssistant.inputType,
    conversationStarters: sourceAssistant.conversationStarters || [],
    
    // Capabilities
    webSearch: sourceAssistant.webSearchEnabled,
    imageGeneration: sourceAssistant.imageGenerationEnabled,
    extendedThinking: sourceAssistant.extendedThinking,
    knowledgeFolderIds: sourceAssistant.knowledgeFolderIds || [],
    
    // Note: input fields, actions, and attachments require special handling (see below)
  };
}

Field Mapping Reference

Get API Response Field	Create API Request Field
`name`	`name`
`description`	`description`
`emojiIcon`	`emoji`
`instruction`	`instruction`
`model`	`model`
`temperature`	`creativity`
`inputType`	`inputType`
`conversationStarters`	`conversationStarters`
`webSearchEnabled`	`webSearch`
`imageGenerationEnabled`	`imageGeneration`
`extendedThinking`	`extendedThinking`
`knowledgeFolderIds`	`knowledgeFolderIds`
`actions`	`actions`
`attachments`	`attachments`

Step 3: Create the Assistant in Target Workspace

Use the Assistant Create API to create the assistant in the target workspace:

async function createAssistantInTarget(assistantConfig, targetApiKey) {
  const response = await axios.post(
    "https://api.langdock.com/assistant/v1/create",
    assistantConfig,
    {
      headers: {
        Authorization: `Bearer ${targetApiKey}`,
        "Content-Type": "application/json"
      }
    }
  );

  return response.data.assistant;
}

Complete Migration Script

Here’s a complete script that combines all steps:

const axios = require("axios");

// Configuration
const SOURCE_API_KEY = "your-source-workspace-api-key";
const TARGET_API_KEY = "your-target-workspace-api-key";
const ASSISTANT_ID_TO_MIGRATE = "550e8400-e29b-41d4-a716-446655440000";

async function migrateAssistant() {
  try {
    // Step 1: Get Assistant from source workspace
    console.log("Fetching Assistant from source workspace...");
    const getResponse = await axios.get(
      "https://api.langdock.com/assistant/v1/get",
      {
        params: { assistantId: ASSISTANT_ID_TO_MIGRATE },
        headers: { Authorization: `Bearer ${SOURCE_API_KEY}` }
      }
    );
    
    const sourceAssistant = getResponse.data.assistant;
    console.log(`Found Assistant: "${sourceAssistant.name}"`);

    // Step 2: Transform configuration for Create API
    const createConfig = {
      name: sourceAssistant.name,
      description: sourceAssistant.description || undefined,
      emoji: sourceAssistant.emojiIcon || undefined,
      instruction: sourceAssistant.instruction || undefined,
      model: sourceAssistant.model,
      creativity: sourceAssistant.temperature,
      inputType: sourceAssistant.inputType,
      conversationStarters: sourceAssistant.conversationStarters || [],
      webSearch: sourceAssistant.webSearchEnabled,
      imageGeneration: sourceAssistant.imageGenerationEnabled,
      extendedThinking: sourceAssistant.extendedThinking,
      knowledgeFolderIds: sourceAssistant.knowledgeFolderIds || [],
      // Note: input fields, actions, and attachments excluded - see "Handling Special Cases"
    };

    // Remove undefined values
    Object.keys(createConfig).forEach(key => {
      if (createConfig[key] === undefined) {
        delete createConfig[key];
      }
    });

    // Step 3: Create Assistant in target workspace
    console.log("Creating Assistant in target workspace...");
    const createResponse = await axios.post(
      "https://api.langdock.com/assistant/v1/create",
      createConfig,
      {
        headers: {
          Authorization: `Bearer ${TARGET_API_KEY}`,
          "Content-Type": "application/json"
        }
      }
    );

    const newAssistant = createResponse.data.assistant;
    console.log(`Migration successful!`);
    console.log(`New Assistant ID: ${newAssistant.id}`);
    console.log(`Assistant name: ${newAssistant.name}`);
    
    return newAssistant;

  } catch (error) {
    if (error.response) {
      console.error(`Error ${error.response.status}: ${JSON.stringify(error.response.data)}`);
    } else {
      console.error("Error:", error.message);
    }
    throw error;
  }
}

migrateAssistant();

Handling Special Cases

Form Fields

The Get API response does not include the slug, options, fileTypes, or emailDomain values required by the Create API. Recreate form fields manually in the target workspace.

Actions (Custom Integrations)

Actions reference integrations that must be enabled in the target workspace. Action UUIDs are specific to each workspace’s integration setup.

Exclude actions from the initial migration and manually configure them in the target workspace after the Assistant is created.

Attachments

Attachment UUIDs reference files stored in the source workspace. These files are not automatically transferred. To migrate attachments:

Download the files from the source workspace
Re-upload them to the target workspace using the Upload Attachment API
Update the Assistant with the new attachment UUIDs

OAuth Connections

Pre-selected OAuth connections are not supported via the API. Users must configure OAuth connections through the Langdock UI after migration.

Migrating Multiple Assistants

To migrate multiple Assistants, simply loop through a list of assistant IDs:

const ASSISTANT_IDS = [
  "Assistant-uuid-1",
  "Assistant-uuid-2",
  "Assistant-uuid-3"
];

async function migrateMultipleAssistants() {
  const results = [];
  
  for (const assistantId of ASSISTANT_IDS) {
    try {
      console.log(`\nMigrating Assistant: ${assistantId}`);
      const newAssistant = await migrateAssistant(assistantId);
      results.push({ 
        sourceId: assistantId, 
        targetId: newAssistant.id, 
        status: "success" 
      });
    } catch (error) {
      results.push({ 
        sourceId: assistantId, 
        status: "failed", 
        error: error.message 
      });
    }
  }
  
  console.log("\n=== Migration Summary ===");
  console.table(results);
}

Post-Migration Checklist

After migrating an Assistant, verify the following in the target workspace:

Assistant appears in the assistants list with correct name and emoji
Description and instructions are correctly transferred
Conversation starters are present
Capabilities (web search, image generation, etc.) are correctly enabled
Input fields are properly configured (for STRUCTURED input type)
Manually configure any OAuth connections through the UI
Re-upload and attach any necessary files
Configure custom actions/integrations if needed
Test the Assistant by sending a message

Limitations

Keep these limitations in mind when planning your migration:

Attachments are not transferred - Files must be re-uploaded to the target workspace
Actions may need reconfiguration - Integration action UUIDs are workspace-specific
OAuth connections require manual setup - Cannot be configured via API
Model access must match - The Create API rejects a model that is not available in the target workspace. Set an available deployment name before migration
Conversation history is not migrated - Only the Assistant configuration is transferred

Migrating to Agents API

The new Agents API offers improved compatibility with modern AI SDKs. The migration process is similar with updated parameter names. See the equivalent guide in the Agents API:

Agent Migration Guide - Uses agentId instead of assistantId

Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

Overview

Completion API

Embedding API

Agents API

Assistants API (Deprecating)

Integrations API

Skills API

Knowledge Folder API

Usage Export API

User Management API

Audit Logs API

Assistant Migration Guide

Overview

Prerequisites

Step 1: Export the Assistant from Source Workspace

Understanding the Response

Step 2: Transform the Configuration

Field Mapping Reference

Step 3: Create the Assistant in Target Workspace

Complete Migration Script

Handling Special Cases

Form Fields

Actions (Custom Integrations)

Attachments

OAuth Connections

Migrating Multiple Assistants

Post-Migration Checklist

Limitations

Migrating to Agents API

​Overview

​Prerequisites

​Step 1: Export the Assistant from Source Workspace

​Understanding the Response

​Step 2: Transform the Configuration

​Field Mapping Reference

​Step 3: Create the Assistant in Target Workspace

​Complete Migration Script

​Handling Special Cases

​Form Fields

​Actions (Custom Integrations)

​Attachments

​OAuth Connections

​Migrating Multiple Assistants

​Post-Migration Checklist

​Limitations

​Migrating to Agents API

Overview

Prerequisites

Step 1: Export the Assistant from Source Workspace

Understanding the Response

Step 2: Transform the Configuration

Field Mapping Reference

Step 3: Create the Assistant in Target Workspace

Complete Migration Script

Handling Special Cases

Form Fields

Actions (Custom Integrations)

Attachments

OAuth Connections

Migrating Multiple Assistants

Post-Migration Checklist

Limitations

Migrating to Agents API