Flagging logs and users for review via API

Configuration Steps

Step 1: Flag a log for review

Use the project logs insert endpoint with the review list metadata structure and merge operation.

curl --location 'https://api.braintrust.dev/v1/project_logs/{project_id}/insert' \
--header 'Authorization: Bearer sk-your-api-key' \
--header 'Content-Type: application/json' \
--data '{
    "events": [{
        "id": "your-log-id",
        "metadata": {
            "~__bt_review_lists": {
                "__bt_default_review_list": {
                    "status": "PENDING"
                }
            }
        },
        "_is_merge": true,
        "_merge_paths": [
            ["metadata", "~__bt_review_lists"]
        ]
    }]
}'

Step 2: Assign a user to the flagged log

Add the user ID to the ~__bt_assignments array in the metadata field.

curl --location 'https://api.braintrust.dev/v1/project_logs/{project_id}/insert' \
--header 'Authorization: Bearer sk-your-api-key' \
--header 'Content-Type: application/json' \
--data '{
    "events": [{
        "id": "your-log-id",
        "metadata": {
            "~__bt_assignments": [
                "user-id-here"
            ],
            "~__bt_review_lists": {
                "__bt_default_review_list": {
                    "status": "PENDING"
                }
            }
        },
        "_is_merge": true,
        "_merge_paths": [
            ["metadata", "~__bt_assignments"]
        ]
    }]
}'

Step 3: Obtain user IDs

Retrieve user IDs from the Braintrust organization settings or users API endpoint before assignment.

Key Fields

~__bt_review_lists: Contains review list configuration with status (PENDING, APPROVED, REJECTED)

~__bt_assignments: Array of user IDs assigned to review the log

_is_merge: Must be true to update existing log entries

_merge_paths: Specifies which metadata fields to merge

Setting ~__bt_assignments alone is sufficient for assigned rows to be marked complete from the Review page. Setting the ~__bt_review_lists status to PENDING remains recommended so the rows also appear in status-based review filters such as Awaiting review.

​Configuration Steps

​Step 1: Flag a log for review

​Step 2: Assign a user to the flagged log

​Step 3: Obtain user IDs

​Key Fields

Configuration Steps

Step 1: Flag a log for review

Step 2: Assign a user to the flagged log

Step 3: Obtain user IDs

Key Fields