Skip to main content
POST
/
v1
/
function
/
{function_id}
/
invoke
Invoke function
curl --request POST \
  --url https://api.braintrust.dev/v1/function/{function_id}/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<unknown>",
  "expected": "<unknown>",
  "metadata": {},
  "tags": [
    "<string>"
  ],
  "messages": [
    {
      "role": "system",
      "content": "",
      "name": "<string>"
    }
  ],
  "parent": {
    "object_type": "project_logs",
    "object_id": "<string>",
    "row_ids": {
      "id": "<string>",
      "span_id": "<string>",
      "root_span_id": "<string>"
    },
    "propagated_event": {}
  },
  "stream": true,
  "mode": "auto",
  "strict": true,
  "mcp_auth": {},
  "overrides": {},
  "version": "<string>"
}
'
"<unknown>"

Authorizations

​
Authorization
string
header
required

Most Braintrust endpoints are authenticated by providing your API key as a header Authorization: Bearer [api_key] to your HTTP request. You can create an API key in the Braintrust organization settings page.

Path Parameters

​
function_id
string<uuid>
required

Function id

Body

application/json

Function invocation parameters

The request to invoke a function

​
input
any | null

Argument to the function, which can be any JSON serializable value

​
expected
any | null

The expected output of the function

​
metadata
object

Any relevant metadata. This will be logged and available as the metadata argument.

​
tags
string[] | null

Any relevant tags to log on the span.

​
messages
(system · object | user · object | assistant · object | tool · object | function · object | developer · object | fallback · object)[]

If the function is an LLM, additional messages to pass along to it

​
parent

Options for tracing the function call

​
stream
boolean | null

Whether to stream the response. If true, results will be returned in the Braintrust SSE format.

​
mode
enum<string> | null

The mode format of the returned value (defaults to 'auto')

Available options:
auto,
parallel,
json,
text,
​
strict
boolean | null

If true, throw an error if one of the variables in the prompt is not present in the input

​
mcp_auth
object

Map of MCP server URL to auth credentials

​
overrides
object

Partial function definition to merge with the function being invoked. Fields are validated against the function type's schema at runtime. For facets: { preprocessor?, prompt?, model? }. For prompts: { model?, ... }.

​
version
string

The version of the function

Response

200 - application/json

Function invocation response

The response is of type unknown.