Run, create, update, and list Pipes - composable, deployable AI agents with a system prompt, model, tools, variables, and memory. POST /v1/pipes/run executes a Pipe over a message array and streams token deltas as Server-Sent Events when stream is true.
openapi: 3.0.3
info:
title: Langbase API
description: >-
Representative OpenAPI description of the Langbase serverless AI developer
platform. All endpoints are served from https://api.langbase.com and
authenticated with a Bearer API key. Generative endpoints (Pipes run,
Agent run) return Server-Sent Events (SSE) when `stream` is true. This
document is a faithful representative model authored by API Evangelist and
is not the provider's official specification.
termsOfService: https://langbase.com/terms
contact:
name: Langbase Support
url: https://langbase.com/support
version: '1.0'
servers:
- url: https://api.langbase.com
description: Langbase production API
security:
- api_key: []
tags:
- name: Pipes
- name: Agent
- name: Memory
- name: Threads
- name: Tools
- name: Parser
- name: Chunker
- name: Embed
paths:
/v1/pipes/run:
post:
operationId: runPipe
tags:
- Pipes
summary: Run a Pipe.
description: >-
Executes a Pipe (deployable AI agent) over a message array. When
`stream` is true the response is delivered as Server-Sent Events (SSE)
with incremental delta content. The response includes an `lb-thread-id`
header for continuing multi-turn conversations.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunPipeRequest'
responses:
'200':
description: A Pipe run completion, or an SSE stream when stream is true.
headers:
lb-thread-id:
schema:
type: string
description: Identifier of the conversation thread.
content:
application/json:
schema:
$ref: '#/components/schemas/RunResponse'
text/event-stream:
schema:
type: string
description: Server-Sent Events stream of completion chunks.
/v1/pipes:
get:
operationId: listPipes
tags:
- Pipes
summary: List Pipes.
responses:
'200':
description: A list of Pipes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pipe'
post:
operationId: createPipe
tags:
- Pipes
summary: Create a Pipe.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePipeRequest'
responses:
'200':
description: The created Pipe.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipe'
/v1/pipes/{name}:
post:
operationId: updatePipe
tags:
- Pipes
summary: Update a Pipe.
parameters:
- in: path
name: name
required: true
schema:
type: string
description: The name of the Pipe to update.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePipeRequest'
responses:
'200':
description: The updated Pipe.
content:
application/json:
schema:
$ref: '#/components/schemas/Pipe'
/v1/agent/run:
post:
operationId: runAgent
tags:
- Agent
summary: Run an agent against any of 100+ LLMs.
description: >-
Runs a prompt against a model specified as `provider:model_id`
(for example `openai:gpt-4o-mini`). Supports tools, generation
controls, and SSE streaming when `stream` is true. A bring-your-own
LLM provider key may be supplied via the `LB-LLM-Key` header.
parameters:
- in: header
name: LB-LLM-Key
required: false
schema:
type: string
description: Optional LLM provider API key for bring-your-own-key runs.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunAgentRequest'
responses:
'200':
description: An agent run response, or an SSE stream when stream is true.
content:
application/json:
schema:
$ref: '#/components/schemas/RunResponse'
text/event-stream:
schema:
type: string
description: Server-Sent Events stream of completion chunks.
/v1/memory:
get:
operationId: listMemories
tags:
- Memory
summary: List memory stores.
responses:
'200':
description: A list of memory stores.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Memory'
post:
operationId: createMemory
tags:
- Memory
summary: Create a memory store.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMemoryRequest'
responses:
'200':
description: The created memory store.
content:
application/json:
schema:
$ref: '#/components/schemas/Memory'
/v1/memory/{name}:
delete:
operationId: deleteMemory
tags:
- Memory
summary: Delete a memory store.
parameters:
- in: path
name: name
required: true
schema:
type: string
responses:
'200':
description: A delete confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
/v1/memory/retrieve:
post:
operationId: retrieveMemory
tags:
- Memory
summary: Retrieve similar chunks (RAG).
description: >-
Runs a semantic similarity search over one or more memory stores and
returns the most relevant chunks, controlled by `topK` (default 20,
max 100) and optional metadata filters.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveMemoryRequest'
responses:
'200':
description: An array of retrieved chunks with similarity scores.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RetrievedChunk'
/v1/memory/{name}/documents:
get:
operationId: listDocuments
tags:
- Memory
summary: List documents in a memory store.
parameters:
- in: path
name: name
required: true
schema:
type: string
responses:
'200':
description: A list of documents.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Document'
post:
operationId: uploadDocument
tags:
- Memory
summary: Upload a document to a memory store.
parameters:
- in: path
name: name
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
documentName:
type: string
document:
type: string
format: binary
required:
- documentName
- document
responses:
'200':
description: The uploaded document.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
/v1/memory/{name}/documents/{documentName}:
delete:
operationId: deleteDocument
tags:
- Memory
summary: Delete a document from a memory store.
parameters:
- in: path
name: name
required: true
schema:
type: string
- in: path
name: documentName
required: true
schema:
type: string
responses:
'200':
description: A delete confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
/v1/threads:
post:
operationId: createThread
tags:
- Threads
summary: Create a conversation thread.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadRequest'
responses:
'200':
description: The created thread.
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
/v1/threads/{threadId}:
get:
operationId: getThread
tags:
- Threads
summary: Get a thread.
parameters:
- in: path
name: threadId
required: true
schema:
type: string
responses:
'200':
description: A thread object.
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
patch:
operationId: updateThread
tags:
- Threads
summary: Update a thread.
parameters:
- in: path
name: threadId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
additionalProperties:
type: string
responses:
'200':
description: The updated thread.
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
delete:
operationId: deleteThread
tags:
- Threads
summary: Delete a thread.
parameters:
- in: path
name: threadId
required: true
schema:
type: string
responses:
'200':
description: A delete confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
/v1/threads/{threadId}/messages:
get:
operationId: listMessages
tags:
- Threads
summary: List messages in a thread.
parameters:
- in: path
name: threadId
required: true
schema:
type: string
responses:
'200':
description: A list of messages.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
post:
operationId: appendMessages
tags:
- Threads
summary: Append messages to a thread.
parameters:
- in: path
name: threadId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
responses:
'200':
description: The appended messages.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Message'
/v1/tools/web-search:
post:
operationId: webSearch
tags:
- Tools
summary: Run a live web search.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebSearchRequest'
responses:
'200':
description: An array of search results.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebSearchResult'
/v1/tools/crawl:
post:
operationId: crawl
tags:
- Tools
summary: Crawl and extract content from web pages.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CrawlRequest'
responses:
'200':
description: An array of crawled page contents.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WebSearchResult'
/v1/parser:
post:
operationId: parseDocument
tags:
- Parser
summary: Parse a document into clean text.
description: >-
Extracts clean text from an uploaded document. Supports PDF, CSV,
XLSX, XLS and more, up to 10 MB.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
document:
type: string
format: binary
documentName:
type: string
contentType:
type: string
required:
- document
- documentName
- contentType
responses:
'200':
description: The parsed document content.
content:
application/json:
schema:
$ref: '#/components/schemas/ParseResponse'
/v1/chunker:
post:
operationId: chunkContent
tags:
- Chunker
summary: Split text into overlapping chunks.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChunkRequest'
responses:
'200':
description: An array of text chunks.
content:
application/json:
schema:
type: array
items:
type: string
/v1/embed:
post:
operationId: embed
tags:
- Embed
summary: Generate embedding vectors.
description: >-
Generates embedding vectors for up to 100 chunks per request, each up
to 8192 characters, using OpenAI, Cohere, or Google embedding models.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedRequest'
responses:
'200':
description: A two-dimensional array of embedding vectors.
content:
application/json:
schema:
type: array
items:
type: array
items:
type: number
format: float
components:
securitySchemes:
api_key:
type: http
scheme: bearer
bearerFormat: apiKey
schemas:
Message:
type: object
properties:
role:
type: string
enum:
- system
- user
- assistant
- tool
content:
type: string
name:
type: string
required:
- role
RunPipeRequest:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
variables:
type: object
additionalProperties:
type: string
description: Dynamic variables for adaptable prompts.
threadId:
type: string
description: Continue an existing conversation thread.
stream:
type: boolean
default: false
description: When true, responses are streamed as Server-Sent Events.
tools:
type: array
items:
type: object
memory:
type: array
items:
type: object
description: Memory objects to override the Pipe defaults.
required:
- messages
RunAgentRequest:
type: object
properties:
model:
type: string
description: Model as provider:model_id, e.g. openai:gpt-4o-mini.
example: openai:gpt-4o-mini
input:
oneOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/Message'
instructions:
type: string
stream:
type: boolean
default: false
tools:
type: array
items:
type: object
temperature:
type: number
top_p:
type: number
max_tokens:
type: integer
required:
- model
- input
RunResponse:
type: object
properties:
completion:
type: string
description: The generated text completion.
raw:
type: object
description: The raw upstream provider response.
usage:
$ref: '#/components/schemas/Usage'
Usage:
type: object
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
Pipe:
type: object
properties:
name:
type: string
description:
type: string
status:
type: string
enum:
- public
- private
model:
type: string
apiKey:
type: string
description: The run key scoped to this Pipe.
CreatePipeRequest:
type: object
properties:
name:
type: string
description:
type: string
status:
type: string
enum:
- public
- private
model:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/Message'
tools:
type: array
items:
type: object
memory:
type: array
items:
type: object
required:
- name
Memory:
type: object
properties:
name:
type: string
description:
type: string
embeddingModel:
type: string
CreateMemoryRequest:
type: object
properties:
name:
type: string
description:
type: string
embeddingModel:
type: string
example: openai:text-embedding-3-large
required:
- name
RetrieveMemoryRequest:
type: object
properties:
query:
type: string
memory:
type: array
items:
type: object
properties:
name:
type: string
topK:
type: integer
default: 20
minimum: 1
maximum: 100
filters:
type: array
items:
type: object
required:
- query
- memory
RetrievedChunk:
type: object
properties:
text:
type: string
similarity:
type: number
format: float
meta:
type: object
additionalProperties:
type: string
Document:
type: object
properties:
name:
type: string
status:
type: string
enum:
- queued
- in_progress
- completed
- failed
enabled:
type: boolean
Thread:
type: object
properties:
id:
type: string
metadata:
type: object
additionalProperties:
type: string
createdAt:
type: integer
CreateThreadRequest:
type: object
properties:
metadata:
type: object
additionalProperties:
type: string
messages:
type: array
items:
$ref: '#/components/schemas/Message'
WebSearchRequest:
type: object
properties:
query:
type: string
service:
type: string
enum:
- exa
totalResults:
type: integer
domains:
type: array
items:
type: string
required:
- query
- service
CrawlRequest:
type: object
properties:
url:
type: array
items:
type: string
service:
type: string
enum:
- spider
maxPages:
type: integer
required:
- url
- service
WebSearchResult:
type: object
properties:
url:
type: string
content:
type: string
ParseResponse:
type: object
properties:
documentName:
type: string
content:
type: string
ChunkRequest:
type: object
properties:
content:
type: string
chunkMaxLength:
type: integer
default: 1024
minimum: 1024
maximum: 30000
chunkOverlap:
type: integer
default: 256
minimum: 256
required:
- content
EmbedRequest:
type: object
properties:
chunks:
type: array
items:
type: string
maxItems: 100
embeddingModel:
type: string
default: openai:text-embedding-3-large
required:
- chunks
DeleteResponse:
type: object
properties:
success:
type: boolean
name:
type: string