Migration Guide from Langbase beta API to v1

This guide will help you migrate from the Langbase beta API to the v1 API. The new API introduces simplified request endpoints and a streamlined body structure.

Deprecation Notice

The beta version of the API has been deprecated and will remain supported until February 28, 2025. We strongly encourage all users to migrate to the new v1 API.

Major Changes

API base URL: A new API base URL has been introduced for v1 API endpoints.
- https://api.langbase.com/v1
Deprecated Endpoints: The generate and chat endpoints have been deprecated and replaced by the run endpoint.
Unified endpoints: Several user/org specific endpoints have been unified for better consistency.
Request body: The structure of the request body for some endpoints has been simplified.

API Endpoint Changes

Here are the key changes in the v1 API endpoints:

`beta` endpoint	`v1` endpoint	Description
`/beta/org/:org/pipes`	`/v1/pipes`	Create/List pipes
`/beta/user/pipes`	`/v1/pipes`	Create/List pipes
`/beta/pipes/:ownerLogin/:pipeName`	`/v1/pipes/:pipeName`	Update pipe
`/beta/pipes/run`	`/v1/pipes/run`	Run pipe
`/beta/generate`	`/v1/pipes/run`	Generate (now unified)
`/beta/chat`	`/v1/pipes/run`	Chat (now unified)
`/beta/org/:org/memorysets`	`/v1/memory`	Create/List memory
`/beta/user/memorysets`	`/v1/memory`	Create/List memory
`/beta/memorysets/:owner/:memoryName`	`/v1/memory/:memoryName`	Delete memory
`/beta/memory/retrieve`	`/v1/memory/retrieve`	Retrieve memory
`/beta/memorysets/:owner/:memoryName/documents`	`/v1/memory/:memoryName/documents`	List documents
`/beta/user/memorysets/documents`	`/v1/memory/:memoryName/documents`	Upload document
`/beta/org/:org/memorysets/documents`	`/v1/memory/:memoryName/documents`	Upload document
`/beta/memorysets/:owner/` `documents/embeddings/retry`	`/v1/memory/:memoryName/documents/` `:documentName/embeddings/retry`	Retry embeddings

Authentication

The authentication process remains the same for the v1 API. You can use the same API key to authenticate your requests.

Run Pipe

Here are the code examples to migrate from the beta to v1 API for running a pipe.

Run Pipe

async function runPipe() {
	const url = 'https://api.langbase.com/v1/pipes/run';

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const data = {
		messages: [ { role: 'user', content: 'Hello!' } ],
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(data),
	});

	const result = await response.json();
	return result;
}

Key Changes:

The generate and chat endpoints have been deprecated and replaced by the run endpoint.

Create Pipe

Here are the code examples to migrate from the beta to v1 API for creating a pipe.

Create Pipe

async function createNewPipe() {
	const url = 'https://api.langbase.com/v1/pipes';
	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const pipe = {
		name: 'ai-agent',
		upsert: true,
		description: 'This is a test ai-agent pipe',
		status: 'public',
		model: 'openai:gpt-4o-mini',
		stream: true,
		json: true,
		store: false,
		moderate: true,
		top_p: 1,
		max_tokens: 1000,
		temperature: 0.7,
		presence_penalty: 1,
		frequency_penalty: 1,
		stop: [],
		tool_choice: 'auto',
		parallel_tool_calls: false,
		messages: [
			{
				role: 'system',
				content: "You're a helpful AI assistant."
			},
			{
				role: 'system',
				content: "Don't ignore these instructions",
				name: 'safety'
			}
		],
		variables: [],
		tools: [],
		memory: [],
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(pipe),
	});

	const newPipe = await response.json();
	return newPipe;
}

Key Changes:

The new upsert property allows you to update a pipe if it already exists.
- Default: false
The model property now accepts a model string in the provider:model_id format.
- Default: openai:gpt-4o-mini
- You can find the list of supported models in the API documentation. Use the copy button to copy/paste the model string for the request body.
The config object has been replaced by individual properties in the v1 API.
The memorysets property has been replaced by memory property.
The prompt object has been replaced by messages array.

Update Pipe

Here are the code examples to migrate from the beta to v1 API for updating a pipe.

Update Pipe

async function updatePipe() {
	const url = `https://api.langbase.com/v1/pipes/${pipeName}`;
	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const pipe = {
		name: 'ai-agent',
		description: 'This is a test ai-agent pipe',
		status: 'public',
		model: 'openai:gpt-4o-mini',
		stream: true,
		json: true,
		store: false,
		moderate: true,
		top_p: 1,
		max_tokens: 1000,
		temperature: 0.7,
		presence_penalty: 1,
		frequency_penalty: 1,
		stop: [],
		tool_choice: 'auto',
		parallel_tool_calls: false,
		messages: [
			{
				role: 'system',
				content: "You're a helpful AI assistant."
			},
			{
				role: 'system',
				content: "Don't ignore these instructions",
				name: 'safety'
			}
		],
		variables: [],
		tools: [],
		memory: [],
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(pipe),
	});

	const updatedPipe = await response.json();
	return updatedPipe;
}

Key Changes:

The ownerLogin has been removed from the v1 update pipe API endpoint.
The model property now accepts a model string in the provider:model_id format.
- Default: openai:gpt-4o-mini
- You can find the list of supported models in the API documentation. Use the copy button to copy/paste the model string for the request body.
The config object has been replaced by individual properties in the v1 API.
The memorysets property has been replaced by memory property.
The prompt object has been replaced by messages array.

List Pipes

Here are the code examples to migrate from the beta to v1 API for listing pipes.

List Pipes

async function listPipes() {
	const url = 'https://api.langbase.com/v1/pipes';

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const response = await fetch(url, {
		method: 'GET',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
	});

	const pipes = await response.json();
	return pipes;
}

Key Changes:

The user/org endpoints have been unified in the v1 list pipes API endpoint.

List Memory

Here are the code examples to migrate from the beta to v1 API for listing memory.

List Memory

async function listMemory() {
	const url = 'https://api.langbase.com/v1/memory';

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const response = await fetch(url, {
		method: 'GET',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
	});

	const memory = await response.json();
	return memory;
}

Key Changes:

The user/org endpoints have been unified in the v1 list memory API endpoint.

Create Memory

Here are the code examples to migrate from the beta to v1 API for creating memory.

Create Memory

async function createMemory() {
	const url = 'https://api.langbase.com/v1/memory';

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const memory = {
		name: 'memory-agent',
		description: 'This is a memory for ai-agent',
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(memory),
	});

	const newMemory = await response.json();
	return newMemory;
}

Key Changes:

The user/org endpoints have been unified in the v1 create memory API endpoint.

Delete Memory

Here are the code examples to migrate from the beta to v1 API for deleting memory.

Delete Memory

async function deleteMemory() {
	const url = `https://api.langbase.com/v1/memory/${memoryName}`;

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const response = await fetch(url, {
		method: 'DELETE',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
	});

	const result = await response.json();
	return result;
}

Key Changes:

The ownerLogin has been removed from the v1 delete memory API endpoint.

Retrieve Memory

Here are the code examples to migrate from the beta to v1 API for retrieving memory.

Retrieve Memory

async function retrieveMemory() {
	const url = 'https://api.langbase.com/v1/memory/retrieve';

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const data = {
		query: 'your query here',
		memory: [
			{ name: 'memory1' },
			{ name: 'memory2' }
		]
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(data),

	});

	const result = await response.json();
	return result;
}

Key Changes:

The ownerLogin property has been removed from the v1 retrieve memory API request body.

List Memory Documents

Here are the code examples to migrate from the beta to v1 API for listing memory documents.

List Memory Documents

async function listMemoryDocuments() {
	const url = `https://api.langbase.com/v1/memory/${memoryName}/documents`;

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const response = await fetch(url, {
		method: 'GET',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
	});

	const documents = await response.json();
	return documents;
}

Key Changes:

The user/org endpoints have been unified in the v1 list memory documents API endpoint.
The ownerLogin has been removed from the v1 list memory documents API endpoint.

Upload Memory Document

Here are the code examples to migrate from the beta to v1 API for uploading memory documents.

Upload Memory Document

async function uploadMemoryDocument() {
	const url = `https://api.langbase.com/v1/memory/${memoryName}/documents`;

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const data = {
		memoryName: 'memory-agent',
		fileName: 'file.pdf',
	};

	const response = await fetch(url, {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
		body: JSON.stringify(data),
	});

	const result = await response.json();
	return result;
}

Key Changes:

The user/org endpoints have been unified in the v1 upload memory document API endpoint.
The ownerLogin has been removed from the v1 upload memory document API request body.

Retry Memory Document Embeddings

Here are the code examples to migrate from the beta to v1 API for retrying memory document embeddings.

Retry embeddings

async function retryMemoryDocumentEmbeddings() {
	const url = `https://api.langbase.com/v1/memory/${memoryName}/documents/${documentName}/embeddings/retry`;

	const apiKey = '<YOUR_API_KEY>'; // Replace with your user/org API key

	const response = await fetch(url, {
		method: 'GET',
		headers: {
			'Content-Type': 'application/json',
			Authorization: `Bearer ${apiKey}`,
		},
	});

	const result = await response.json();
	return result;
}

Key Changes:

The owner has been replaced by memoryName and documentName in the v1 retry memory document embeddings API endpoint.

API Reference

Migration Guide from Langbase beta API to v1

Run Pipe

Create Pipe

Update Pipe

List Pipes

List Memory

Create Memory

Delete Memory

Retrieve Memory

List Memory Documents

Upload Memory Document

Retry embeddings