Functions - Docs - Braintrust

GET

/v1/function

List functions

List out all functions. The functions are sorted by creation date, with the most recently-created functions coming first

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.

In: header

Query Parameters

`limit`integer | null

Limit the number of objects to return

Minimum: 0

`starting_after`string

Pagination cursor id.

For example, if the final item in the last page you fetched had an id of foo, pass starting_after=foo to fetch the next page. Note: you may only pass one of starting_after and ending_before

Format: "uuid"

`ending_before`string

Pagination cursor id.

For example, if the initial item in the last page you fetched had an id of foo, pass ending_before=foo to fetch the previous page. Note: you may only pass one of starting_after and ending_before

Format: "uuid"

`ids`Any properties in string, array<string>

Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times

`function_name`string

Name of the function to search for

`project_name`string

Name of the project to search for

`project_id`string

Project id

Format: "uuid"

`slug`string

Retrieve prompt with a specific slug

`version`string

Retrieve prompt at a specific version.

The version id can either be a transaction id (e.g. '1000192656880881099') or a version identifier (e.g. '81cd05ee665fdfb3').

`org_name`string

Filter search results to within a particular organization

curl -X GET "https://api.braintrust.dev/v1/function?limit=0&starting_after=497f6eca-6276-4993-bfeb-53cbbbba6f08&ending_before=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&function_name=string&project_name=string&project_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&slug=string&version=string&org_name=string" \
  -H "Authorization: Bearer <token>"

Returns a list of function objects

{
  "objects": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "_xact_id": "string",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "log_id": "p",
      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
      "name": "string",
      "slug": "string",
      "description": "string",
      "created": "2019-08-24T14:15:22Z",
      "prompt_data": {
        "prompt": {
          "type": "completion",
          "content": "string"
        },
        "options": {
          "model": "string",
          "params": {
            "use_cache": true,
            "temperature": 0,
            "top_p": 0,
            "max_tokens": 0,
            "max_completion_tokens": 0,
            "frequency_penalty": 0,
            "presence_penalty": 0,
            "response_format": {
              "type": "json_object"
            },
            "tool_choice": "auto",
            "function_call": "auto",
            "n": 0,
            "stop": [
              "string"
            ],
            "reasoning_effort": "low"
          },
          "position": "string"
        },
        "parser": {
          "type": "llm_classifier",
          "use_cot": true,
          "choice_scores": {
            "property1": 1,
            "property2": 1
          }
        },
        "tool_functions": [
          {
            "type": "function",
            "id": "string"
          }
        ],
        "origin": {
          "prompt_id": "string",
          "project_id": "string",
          "prompt_version": "string"
        }
      },
      "tags": [
        "string"
      ],
      "metadata": {
        "property1": null,
        "property2": null
      },
      "function_type": "llm",
      "function_data": {
        "type": "prompt"
      },
      "origin": {
        "object_type": "organization",
        "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
        "internal": true
      },
      "function_schema": {
        "parameters": null,
        "returns": null
      }
    }
  ]
}

POST

/v1/function

Create function

Create a new function. If there is an existing function in the project with the same slug as the one specified in the request, will return the existing function unmodified

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Any desired information about the new function object

`project_id`
Required
string

Unique identifier for the project that the prompt belongs under

Format: "uuid"

`name`
Required
string

Name of the prompt

Minimum length: 1

`slug`
Required
string

Unique identifier for the prompt

Minimum length: 1

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`tags`array<string> | null

A list of tags for the prompt

`function_type`string | null

Value in: "llm" | "scorer" | "task" | "tool" | null

`function_data`
Required
Any properties in prompt, code, global

`origin`object | null

`function_schema`object | null

JSON schema for the function's parameters and return type

curl -X POST "https://api.braintrust.dev/v1/function" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "name": "string",
    "slug": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "tags": [
      "string"
    ],
    "function_type": "llm",
    "function_data": {
      "type": "prompt"
    },
    "origin": {
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "internal": true
    },
    "function_schema": {
      "parameters": null,
      "returns": null
    }
  }'

Returns the new function object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm",
  "function_data": {
    "type": "prompt"
  },
  "origin": {
    "object_type": "organization",
    "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
    "internal": true
  },
  "function_schema": {
    "parameters": null,
    "returns": null
  }
}

PUT

/v1/function

Create or replace function

Create or replace function. If there is an existing function in the project with the same slug as the one specified in the request, will replace the existing function with the provided fields

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Any desired information about the new function object

`project_id`
Required
string

Unique identifier for the project that the prompt belongs under

Format: "uuid"

`name`
Required
string

Name of the prompt

Minimum length: 1

`slug`
Required
string

Unique identifier for the prompt

Minimum length: 1

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`tags`array<string> | null

A list of tags for the prompt

`function_type`string | null

Value in: "llm" | "scorer" | "task" | "tool" | null

`function_data`
Required
Any properties in prompt, code, global

`origin`object | null

`function_schema`object | null

JSON schema for the function's parameters and return type

curl -X PUT "https://api.braintrust.dev/v1/function" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
    "name": "string",
    "slug": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "tags": [
      "string"
    ],
    "function_type": "llm",
    "function_data": {
      "type": "prompt"
    },
    "origin": {
      "object_type": "organization",
      "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
      "internal": true
    },
    "function_schema": {
      "parameters": null,
      "returns": null
    }
  }'

Returns the new function object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm",
  "function_data": {
    "type": "prompt"
  },
  "origin": {
    "object_type": "organization",
    "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
    "internal": true
  },
  "function_schema": {
    "parameters": null,
    "returns": null
  }
}

GET

/v1/function/{function_id}

Get function

Get a function object by its id

Authorization

`Authorization`
Required
Bearer <token>

In: header

Path Parameters

`function_id`
Required
string

Function id

Format: "uuid"

curl -X GET "https://api.braintrust.dev/v1/function/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the function object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm",
  "function_data": {
    "type": "prompt"
  },
  "origin": {
    "object_type": "organization",
    "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
    "internal": true
  },
  "function_schema": {
    "parameters": null,
    "returns": null
  }
}

PATCH

/v1/function/{function_id}

Partially update function

Partially update a function object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Fields to update

`name`string | null

Name of the prompt

`description`string | null

Textual description of the prompt

`prompt_data`object | null

The prompt, model, and its parameters

`function_data`Any properties in prompt, code, global, null

`tags`array<string> | null

A list of tags for the prompt

Path Parameters

`function_id`
Required
string

Function id

Format: "uuid"

curl -X PATCH "https://api.braintrust.dev/v1/function/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "prompt_data": {
      "prompt": {
        "type": "completion",
        "content": "string"
      },
      "options": {
        "model": "string",
        "params": {
          "use_cache": true,
          "temperature": 0,
          "top_p": 0,
          "max_tokens": 0,
          "max_completion_tokens": 0,
          "frequency_penalty": 0,
          "presence_penalty": 0,
          "response_format": {
            "type": "json_object"
          },
          "tool_choice": "auto",
          "function_call": "auto",
          "n": 0,
          "stop": [
            "string"
          ],
          "reasoning_effort": "low"
        },
        "position": "string"
      },
      "parser": {
        "type": "llm_classifier",
        "use_cot": true,
        "choice_scores": {
          "property1": 1,
          "property2": 1
        }
      },
      "tool_functions": [
        {
          "type": "function",
          "id": "string"
        }
      ],
      "origin": {
        "prompt_id": "string",
        "project_id": "string",
        "prompt_version": "string"
      }
    },
    "function_data": {
      "type": "prompt"
    },
    "tags": [
      "string"
    ]
  }'

Returns the function object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm",
  "function_data": {
    "type": "prompt"
  },
  "origin": {
    "object_type": "organization",
    "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
    "internal": true
  },
  "function_schema": {
    "parameters": null,
    "returns": null
  }
}

DELETE

/v1/function/{function_id}

Delete function

Delete a function object by its id

Authorization

`Authorization`
Required
Bearer <token>

In: header

Path Parameters

`function_id`
Required
string

Function id

Format: "uuid"

curl -X DELETE "https://api.braintrust.dev/v1/function/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Authorization: Bearer <token>"

Returns the deleted function object

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "_xact_id": "string",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "log_id": "p",
  "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  "name": "string",
  "slug": "string",
  "description": "string",
  "created": "2019-08-24T14:15:22Z",
  "prompt_data": {
    "prompt": {
      "type": "completion",
      "content": "string"
    },
    "options": {
      "model": "string",
      "params": {
        "use_cache": true,
        "temperature": 0,
        "top_p": 0,
        "max_tokens": 0,
        "max_completion_tokens": 0,
        "frequency_penalty": 0,
        "presence_penalty": 0,
        "response_format": {
          "type": "json_object"
        },
        "tool_choice": "auto",
        "function_call": "auto",
        "n": 0,
        "stop": [
          "string"
        ],
        "reasoning_effort": "low"
      },
      "position": "string"
    },
    "parser": {
      "type": "llm_classifier",
      "use_cot": true,
      "choice_scores": {
        "property1": 1,
        "property2": 1
      }
    },
    "tool_functions": [
      {
        "type": "function",
        "id": "string"
      }
    ],
    "origin": {
      "prompt_id": "string",
      "project_id": "string",
      "prompt_version": "string"
    }
  },
  "tags": [
    "string"
  ],
  "metadata": {
    "property1": null,
    "property2": null
  },
  "function_type": "llm",
  "function_data": {
    "type": "prompt"
  },
  "origin": {
    "object_type": "organization",
    "object_id": "463a83d0-a816-4902-abba-2486e0c0a0bb",
    "internal": true
  },
  "function_schema": {
    "parameters": null,
    "returns": null
  }
}

POST

/v1/function/{function_id}/invoke

Invoke function

Invoke a function.

Authorization

`Authorization`
Required
Bearer <token>

In: header

Request Body

application/jsonOptional

Function invocation parameters

`input`null

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

`messages`array<Any properties in system, user, assistant, tool, function, fallback>

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

`parent`Any properties in span_parent_struct, string

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`string | null

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

Value in: "auto" | "parallel" | null

`version`string

The version of the function

Path Parameters

`function_id`
Required
string

Function id

Format: "uuid"

curl -X POST "https://api.braintrust.dev/v1/function/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoke" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": null,
    "messages": [
      {
        "content": "",
        "role": "system",
        "name": "string"
      }
    ],
    "parent": {
      "object_type": "project_logs",
      "object_id": "string",
      "row_ids": {
        "id": "string",
        "span_id": "string",
        "root_span_id": "string"
      },
      "propagated_event": {
        "property1": null,
        "property2": null
      }
    },
    "stream": true,
    "mode": "auto",
    "version": "string"
  }'

Function invocation response

null

Query

AuthorizationRequiredBearer <token>

limitinteger | null

starting_afterstring

ending_beforestring

idsAny properties in string, array<string>

Object 1

function_namestring

project_namestring

project_idstring

slugstring

versionstring

org_namestring

Response

TypeScript

Body

AuthorizationRequiredBearer <token>

project_idRequiredstring

nameRequiredstring

slugRequiredstring

descriptionstring | null

prompt_dataobject | null

Attributes

tagsarray<string> | null

function_typestring | null

function_dataRequiredAny properties in prompt, code, global

prompt

code

global

originobject | null

Attributes

function_schemaobject | null

Attributes

Response

TypeScript

Body

AuthorizationRequiredBearer <token>

project_idRequiredstring

nameRequiredstring

slugRequiredstring

descriptionstring | null

prompt_dataobject | null

Attributes

tagsarray<string> | null

function_typestring | null

function_dataRequiredAny properties in prompt, code, global

prompt

code

global

originobject | null

Attributes

function_schemaobject | null

Attributes

Response

TypeScript

Path

AuthorizationRequiredBearer <token>

function_idRequiredstring

Response

TypeScript

Path

Body

AuthorizationRequiredBearer <token>

namestring | null

descriptionstring | null

prompt_dataobject | null

Attributes

function_dataAny properties in prompt, code, global, null

prompt

code

global

tagsarray<string> | null

function_idRequiredstring

Response

TypeScript

Path

AuthorizationRequiredBearer <token>

function_idRequiredstring

Response

TypeScript

`Authorization`
Required
Bearer <token>

`limit`integer | null

`starting_after`string

`ending_before`string

`ids`Any properties in string, array<string>

`function_name`string

`project_name`string

`project_id`string

`slug`string

`version`string

`org_name`string

`Authorization`
Required
Bearer <token>

`project_id`
Required
string

`name`
Required
string

`slug`
Required
string

`description`string | null

`prompt_data`object | null

`tags`array<string> | null

`function_type`string | null

`function_data`
Required
Any properties in prompt, code, global

`origin`object | null

`function_schema`object | null

`Authorization`
Required
Bearer <token>

`project_id`
Required
string

`name`
Required
string

`slug`
Required
string

`description`string | null

`prompt_data`object | null

`tags`array<string> | null

`function_type`string | null

`function_data`
Required
Any properties in prompt, code, global

`origin`object | null

`function_schema`object | null

`Authorization`
Required
Bearer <token>

`function_id`
Required
string

`Authorization`
Required
Bearer <token>

`name`string | null

`description`string | null

`prompt_data`object | null

`function_data`Any properties in prompt, code, global, null

`tags`array<string> | null

`function_id`
Required
string

`Authorization`
Required
Bearer <token>

`function_id`
Required
string

`Authorization`
Required
Bearer <token>

`input`null

`messages`array<Any properties in system, user, assistant, tool, function, fallback>

`parent`Any properties in span_parent_struct, string

`stream`boolean | null

`mode`string | null

`version`string

`function_id`
Required
string