Skip to main content
POST
Invoke function

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

request_source
string

A label identifying the caller, used to attribute usage

input
any

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

expected
any

The expected output of the function

metadata
object | null

Any relevant metadata to log on the span. For prompts, this is available as the metadata template variable. For code functions, this is passed through hooks and is not added to input.

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,
null
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 | null

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?, ... }.

endpoint_name
string | null

Name of the AI provider secret to pin this invocation to.

version
string

The version of the function

Response

Function invocation response. Scorer results follow the ScoreResult schema: a single score defaults to the function name when unnamed; arrays require a unique name for every score.