API Reference

API Endpoints for LangDB

Create chat completion

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

modelstringRequired

ID of the model to use. This can be either a specific model ID or a virtual model identifier.

Example: gpt-4o

temperaturenumber · max: 2Optional

Sampling temperature.

Example: 0.8

top_pnumber · max: 1Optional

Nucleus sampling probability.

max_tokensinteger · min: 1Optional

The maximum number of tokens that can be generated in the chat completion.

ninteger · min: 1Optional

How many chat completion choices to generate for each input message.

Default: 1

stopone ofOptional

Up to 4 sequences where the API will stop generating further tokens.

stringOptional

string[]Optional

presence_penaltynumber · min: -2 · max: 2Optional

Penalize new tokens based on whether they appear in the text so far.

frequency_penaltynumber · min: -2 · max: 2Optional

Penalize new tokens based on their existing frequency in the text so far.

logprobsbooleanOptional

Whether to return log probabilities of the output tokens.

top_logprobsinteger · min: 1 · max: 20Optional

The number of most likely tokens to return at each position, for which the log probabilities are returned. Requires logprobs=true.

seedintegerOptional

If specified, the backend will make a best effort to return deterministic results.

response_formatone ofOptional

Format for the model's response.

string · enumOptionalPossible values:

tool_choiceone ofOptional

Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.

string · enumOptionalPossible values:

parallel_tool_callsbooleanOptional

Whether to enable parallel function calling during tool use.

Default: true

streambooleanOptional

Whether to stream back partial progress.

Default: false

userstringOptionalDeprecated

Deprecated. This field is being replaced by safety_identifier and prompt_cache_key. Use prompt_cache_key to maintain caching optimizations. A stable identifier for your end-users was previously used to boost cache hit rates by better bucketing similar requests and to help detect and prevent abuse.

safety_identifierstringOptional

Stable identifier for your end-users, used to help detect and prevent abuse. Prefer this over user. For caching optimization, combine with prompt_cache_key.

prompt_cache_keystringOptional

Used to cache responses for similar requests to optimize cache hit rates. LangDB supports prompt caching; see https://docs.langdb.ai/features/prompt-caching. Can be used instead of the user field for cache bucketing.

Responses

200

application/json

post

/v1/chat/completions

POST /v1/chat/completions HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 859

{
  "model": "router/dynamic",
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about recursion in programming."
    }
  ],
  "temperature": 0.8,
  "max_tokens": 1000,
  "top_p": 0.9,
  "frequency_penalty": 0.1,
  "presence_penalty": 0.2,
  "stream": false,
  "response_format": "json_object",
  "mcp_servers": [
    {
      "server_url": "wss://your-mcp-server.com/ws?config=your_encoded_config",
      "type": "ws"
    }
  ],
  "router": {
    "type": "conditional",
    "routes": [
      {
        "conditions": {
          "all": [
            {
              "extra.user.tier": {
                "$eq": "premium"
              }
            }
          ]
        },
        "name": "premium_user",
        "targets": {
          "$any": [
            "openai/gpt-4.1-mini",
            "xai/grok-4",
            "anthropic/claude-sonnet-4"
          ],
          "filter": {
            "error_rate": {
              "$lt": 0.01
            }
          },
          "sort_by": "ttft",
          "sort_order": "min"
        }
      },
      {
        "name": "basic_user",
        "targets": "openai/gpt-4.1-nano"
      }
    ]
  },
  "extra": {
    "guards": [
      "word_count_validator_bd4bdnun",
      "toxicity_detection_4yj4cdvu"
    ],
    "user": {
      "id": "7",
      "name": "mrunmay",
      "tier": "premium",
      "tags": [
        "coding",
        "software"
      ]
    }
  }
}

200

{
  "id": "text",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 1,
      "message": {
        "role": "assistant",
        "content": "text",
        "tool_calls": [
          {
            "id": "text",
            "type": "function",
            "function": {
              "name": "text",
              "arguments": "text"
            }
          }
        ],
        "function_call": {
          "name": "text",
          "arguments": "text"
        }
      },
      "logprobs": {
        "content": [
          {
            "token": "text",
            "logprob": 1
          }
        ],
        "refusal": [
          {
            "token": "text",
            "logprob": 1
          }
        ]
      }
    }
  ],
  "created": 1,
  "model": "text",
  "system_fingerprint": "text",
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1,
    "prompt_tokens_details": {
      "cached_tokens": 1,
      "cache_creation_tokens": 1,
      "audio_tokens": 1
    },
    "completion_tokens_details": {
      "reasoning_tokens": 1,
      "accepted_prediction_tokens": 1,
      "rejected_prediction_tokens": 1,
      "audio_tokens": 1
    },
    "cost": 1
  }
}

Create embeddings

post

Creates an embedding vector representing the input text or token arrays.

Authorizations

Body

modelstringRequired

ID of the model to use for generating embeddings.

Example: text-embedding-ada-002

inputone ofRequired

stringOptional

The text to embed.

string[]Optional

Array of text strings to embed.

encoding_formatstring · enumOptional

The format to return the embeddings in.

Default: floatPossible values:

dimensionsinteger · min: 1 · max: 1536Optional

The number of dimensions the resulting embeddings should have.

Example: 1536

Responses

200

Successful response with embeddings

application/json

post

/v1/embeddings

POST /v1/embeddings HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "input": "The food was delicious and the waiter was kind.",
  "model": "text-embedding-ada-002",
  "encoding_format": "float",
  "dimensions": 1536
}

200

Successful response with embeddings

{
  "data": [
    {
      "embedding": [
        1
      ],
      "index": 1
    }
  ],
  "model": "text",
  "usage": {
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}

Retrieve a list of threads

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

limitinteger · min: 1RequiredExample: 10

offsetintegerRequiredExample: 100

Responses

200

A list of threads with pagination info

application/json

post

/threads

POST /threads HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "limit": 10,
  "offset": 100
}

200

A list of threads with pagination info

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-11-02T19:57:17.129Z",
      "updated_at": "2025-11-02T19:57:17.129Z",
      "model_name": "text",
      "project_id": "text",
      "score": 1,
      "title": "text",
      "user_id": "text"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 100,
    "total": 10
  }
}

Retrieve messages for a specific thread

get

Authorizations

Path parameters

thread_idstring · uuidRequired

The ID of the thread to retrieve messages from

Header parameters

X-Project-IdstringRequired

LangDB project ID

Responses

200

A list of messages for the given thread

application/json

get

/threads/{thread_id}/messages

GET /threads/{thread_id}/messages HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Accept: */*

200

A list of messages for the given thread

[
  {
    "model_name": "gpt-4o-mini",
    "thread_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "langdb",
    "content_type": "Text",
    "content": "text",
    "content_array": [
      "text"
    ],
    "type": "system",
    "tool_call_id": "123e4567-e89b-12d3-a456-426614174000",
    "tool_calls": "text",
    "created_at": "2025-01-29 10:25:00.736000",
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
]

Retrieve the total cost for a specific thread

get

Authorizations

Path parameters

thread_idstring · uuidRequired

The ID of the thread for which to retrieve cost information

Header parameters

X-Project-IdstringRequired

LangDB project ID

Responses

200

The total cost and token usage for the specified thread

application/json

get

/threads/{thread_id}/cost

GET /threads/{thread_id}/cost HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Accept: */*

200

The total cost and token usage for the specified thread

{
  "total_cost": 0.022226999999999997,
  "total_output_tokens": 171,
  "total_input_tokens": 6725
}

Fetch analytics data

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

start_time_usinteger · int64OptionalDeprecated

Start time in microseconds.

Example: 1693062345678

end_time_usinteger · int64OptionalDeprecated

End time in microseconds.

Example: 1693082345678

periodstring · enumOptional

Time period for filtering data. If provided, start_time and end_time will be ignored.

Example: last_monthPossible values:

Responses

200

Successful response

application/json

post

/analytics

POST /analytics HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "period": "last_month"
}

200

Successful response

{
  "timeseries": [
    {
      "hour": "2025-02-20 18:00:00",
      "total_cost": 12.34,
      "total_requests": 1000,
      "avg_duration": 250.5,
      "duration": 245.7,
      "duration_p99": 750.2,
      "duration_p95": 500.1,
      "duration_p90": 400.8,
      "duration_p50": 200.3,
      "total_duration": 1,
      "total_input_tokens": 1,
      "total_output_tokens": 1,
      "error_rate": 1,
      "error_request_count": 1,
      "avg_ttft": 1,
      "ttft": 1,
      "ttft_p99": 1,
      "ttft_p95": 1,
      "ttft_p90": 1,
      "ttft_p50": 1,
      "tps": 1,
      "tps_p99": 1,
      "tps_p95": 1,
      "tps_p90": 1,
      "tps_p50": 1,
      "tpot": 0.85,
      "tpot_p99": 1.5,
      "tpot_p95": 1.2,
      "tpot_p90": 1,
      "tpot_p50": 0.75,
      "tag_tuple": [
        "text"
      ]
    }
  ],
  "start_time": 1,
  "end_time": 1
}

Fetch analytics summary

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

start_time_usinteger · int64OptionalDeprecatedExample: 1693062345678

end_time_usinteger · int64OptionalDeprecatedExample: 1693082345678

periodstring · enumOptional

Time period for filtering data. If provided, start_time and end_time will be ignored.

Example: last_monthPossible values:

groupBystring[]RequiredExample: ["provider"]

Responses

200

Successful response

application/json

post

/analytics/summary

POST /analytics/summary HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "period": "last_month",
  "groupBy": [
    "provider"
  ]
}

200

Successful response

{
  "summary": [
    {
      "tag_tuple": [
        "openai",
        "gpt-4"
      ],
      "total_cost": 156.78,
      "total_requests": 5000,
      "total_duration": 1250000,
      "avg_duration": 250,
      "duration": 245.5,
      "duration_p99": 750,
      "duration_p95": 500,
      "duration_p90": 400,
      "duration_p50": 200,
      "total_input_tokens": 100000,
      "total_output_tokens": 50000,
      "avg_ttft": 100,
      "ttft": 98.5,
      "ttft_p99": 300,
      "ttft_p95": 200,
      "ttft_p90": 150,
      "ttft_p50": 80,
      "tps": 10.5,
      "tps_p99": 20,
      "tps_p95": 15,
      "tps_p90": 12,
      "tps_p50": 8,
      "tpot": 0.85,
      "tpot_p99": 1.5,
      "tpot_p95": 1.2,
      "tpot_p90": 1,
      "tpot_p50": 0.75,
      "error_rate": 1,
      "error_request_count": 1
    }
  ],
  "start_time": 1,
  "end_time": 1
}

Get total usage

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

start_time_usinteger · int64OptionalDeprecatedExample: 1693062345678

end_time_usinteger · int64OptionalDeprecated

End time in microseconds.

Example: 1693082345678

periodstring · enumOptional

Time period for filtering data. If provided, start_time and end_time will be ignored.

Example: last_monthPossible values:

Responses

200

application/json

post

/usage/total

POST /usage/total HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "period": "last_month"
}

200

{
  "models": [
    {
      "provider": "openai",
      "model_name": "gpt-4o",
      "total_input_tokens": 3196182,
      "total_output_tokens": 74096,
      "total_cost": 10.4776979999,
      "cost_per_input_token": 3,
      "cost_per_output_token": 12
    }
  ],
  "total": {
    "total_input_tokens": 4181386,
    "total_output_tokens": 206547,
    "total_cost": 11.8904386859
  },
  "period_start": 1737504000,
  "period_end": 1740120949
}

Get usage by model

post

Authorizations

Header parameters

X-Project-IdstringRequired

LangDB project ID

Body

start_time_usinteger · int64OptionalExample: 1693062345678

end_time_usinteger · int64Optional

min_unitstring · enumOptional

The granularity of the returned usage data.

Example: hourPossible values:

Responses

200

Successful response

application/json

post

/usage/models

POST /usage/models HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "start_time_us": 1693062345678,
  "end_time_us": 1,
  "min_unit": "hour"
}

200

Successful response

{
  "models": [
    {
      "hour": "2025-02-15 09:00:00",
      "provider": "openai",
      "model_name": "gpt-4o",
      "total_input_tokens": 451235,
      "total_output_tokens": 2553,
      "total_cost": 1.3843410000000005
    }
  ],
  "period_start": 1737504000000000,
  "period_end": 1740121147931000
}

Retrieve pricing information

get

Returns the pricing details for LangDB services.

Responses

200

Successful retrieval of pricing information

application/json

get

/pricing

GET /pricing HTTP/1.1
Host: api.us-east-1.langdb.ai
Accept: */*

200

Successful retrieval of pricing information

{
  "model": "gpt-3.5-turbo-0125",
  "provider": "openai",
  "price": {
    "per_input_token": 0.5,
    "per_output_token": 1.5,
    "valid_from": null
  },
  "input_formats": [
    "text"
  ],
  "output_formats": [
    "text"
  ],
  "capabilities": [
    "tools"
  ],
  "type": "completions",
  "limits": {
    "max_context_size": 16385
  }
}

List models

get

Responses

200

application/json

get

/models

GET /models HTTP/1.1
Host: api.us-east-1.langdb.ai
Accept: */*

200

{
  "object": "list",
  "data": [
    {
      "id": "o1-mini",
      "object": "model",
      "created": 1686935002,
      "owned_by": "openai"
    }
  ]
}

Create a new model

post

Authorizations

Header parameters

X-Admin-KeystringRequired

LangDB Admin Key

Body

model_namestringRequiredExample: my-model

descriptionstringRequiredExample: A custom completions model for text and image inputs

provider_info_idstring · uuidRequiredExample: e2e9129b-6661-4eeb-80a2-0c86964974c9

project_idstringRequiredExample: 55f4a12b-74c8-4294-8e4b-537f13fc3861

publicbooleanOptionalExample: false

request_response_mappingstringOptionalExample: openai-compatible

model_typestringRequiredExample: completions

input_token_pricenumber · float | nullableOptionalExample: 0.00001

output_token_pricenumber · float | nullableOptionalExample: 0.00003

context_sizeinteger | nullableOptionalExample: 128000

capabilitiesstring[]OptionalExample: ["tools"]

input_typesstring[]OptionalExample: ["text","image"]

output_typesstring[]OptionalExample: ["text","image"]

tagsstring[]Optional

mp_pricenumber · float | nullableOptional

owner_namestringRequiredExample: openai

priorityintegerRequiredExample: 0

model_name_in_providerstringOptionalExample: my-model-v1.2

parametersobjectOptional

Additional configuration parameters

Example:

{"top_k":{"default":0,"description":"Limits the token sampling to only the top K tokens.","min":0,"required":false,"step":1,"type":"int"},"top_p":{"default":1,"description":"Nucleus sampling alternative.","max":1,"min":0,"required":false,"step":0.05,"type":"float"}}

Responses

200

Created

application/json

post

/admin/models

POST /admin/models HTTP/1.1
Host: api.xxx.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Admin-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 884

{
  "model_name": "my-model",
  "description": "A custom completions model for text and image inputs",
  "provider_info_id": "e2e9129b-6661-4eeb-80a2-0c86964974c9",
  "project_id": "55f4a12b-74c8-4294-8e4b-537f13fc3861",
  "public": false,
  "request_response_mapping": "openai-compatible",
  "model_type": "completions",
  "input_token_price": 0.00001,
  "output_token_price": 0.00003,
  "context_size": 128000,
  "capabilities": [
    "tools"
  ],
  "input_types": [
    "text",
    "image"
  ],
  "output_types": [
    "text",
    "image"
  ],
  "tags": [],
  "type_prices": {
    "text_generation": 0.00002
  },
  "mp_price": null,
  "owner_name": "openai",
  "priority": 0,
  "model_name_in_provider": "my-model-v1.2",
  "parameters": {
    "top_k": {
      "default": 0,
      "description": "Limits the token sampling to only the top K tokens.",
      "min": 0,
      "required": false,
      "step": 1,
      "type": "int"
    },
    "top_p": {
      "default": 1,
      "description": "Nucleus sampling alternative.",
      "max": 1,
      "min": 0,
      "required": false,
      "step": 0.05,
      "type": "float"
    }
  }
}

200

Created

{
  "id": "55f4a12b-74c8-4294-8e4b-537f13fc3861",
  "model_name": "my-model",
  "description": "A custom completions model for text and image inputs",
  "provider_info_id": "e2e9129b-6661-4eeb-80a2-0c86964974c9",
  "model_type": "completions",
  "input_token_price": "0.00001",
  "output_token_price": "0.00003",
  "context_size": 128000,
  "capabilities": [
    "tools"
  ],
  "input_types": [
    "text",
    "image"
  ],
  "output_types": [
    "text",
    "image"
  ],
  "tags": [],
  "type_prices": null,
  "mp_price": null,
  "model_name_in_provider": "my-model-v1.2",
  "owner_name": "openai",
  "priority": 0,
  "parameters": {
    "top_k": {
      "default": 0,
      "description": "Limits the token sampling to only the top K tokens.",
      "min": 0,
      "required": false,
      "step": 1,
      "type": "int"
    },
    "top_p": {
      "default": 1,
      "description": "An alternative to sampling with temperature.",
      "max": 1,
      "min": 0,
      "required": false,
      "step": 0.05,
      "type": "float"
    }
  }
}

Set custom prices for imported models

post

Set custom pricing for models imported from providers like Bedrock, Azure, Vertex that do not have built-in pricing

Authorizations

Path parameters

project_idstring · uuidRequired

UUID of the project

Example: 25a0b7d9-86cf-448d-8395-66e9073d876f

Body

Request body for setting custom prices on imported models

Responses

200

Custom prices set successfully

application/json

post

/projects/{project_id}/custom_prices

POST /projects/{project_id}/custom_prices HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "bedrock/twelvelabs.pegasus-1-2-v1:0": {
    "per_input_token": 1.23,
    "per_output_token": 2.12
  }
}

200

Custom prices set successfully

{
  "bedrock/ai21.jamba-1-5-large-v1:0": {
    "per_input_token": 1.23,
    "per_output_token": 2.12
  }
}

PreviousGetting Started

Last updated 1 month ago

Was this helpful?