Edit a benchmark from a JSON spec

curl --request POST \
  --url https://api.benchgen.com/api/competitions/{id}/edit_spec/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Unit Conversion Basics, revised",
  "description": "<string>",
  "terms": "<string>",
  "contact_email": "jsmith@example.com",
  "organization_name": "<string>",
  "reward": "<string>",
  "report": "<string>",
  "pages": [
    {
      "title": "<string>",
      "content": "<string>"
    }
  ],
  "items": [
    {
      "question": "<string>",
      "answer": "<string>",
      "choices": [
        "<string>"
      ],
      "context": "<string>",
      "group": "<string>"
    }
  ]
}
'

import requests

url = "https://api.benchgen.com/api/competitions/{id}/edit_spec/"

payload = {
    "title": "Unit Conversion Basics, revised",
    "description": "<string>",
    "terms": "<string>",
    "contact_email": "jsmith@example.com",
    "organization_name": "<string>",
    "reward": "<string>",
    "report": "<string>",
    "pages": [
        {
            "title": "<string>",
            "content": "<string>"
        }
    ],
    "items": [
        {
            "question": "<string>",
            "answer": "<string>",
            "choices": ["<string>"],
            "context": "<string>",
            "group": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Unit Conversion Basics, revised',
    description: '<string>',
    terms: '<string>',
    contact_email: 'jsmith@example.com',
    organization_name: '<string>',
    reward: '<string>',
    report: '<string>',
    pages: [{title: '<string>', content: '<string>'}],
    items: [
      {
        question: '<string>',
        answer: '<string>',
        choices: ['<string>'],
        context: '<string>',
        group: '<string>'
      }
    ]
  })
};

fetch('https://api.benchgen.com/api/competitions/{id}/edit_spec/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.benchgen.com/api/competitions/{id}/edit_spec/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Unit Conversion Basics, revised',
    'description' => '<string>',
    'terms' => '<string>',
    'contact_email' => 'jsmith@example.com',
    'organization_name' => '<string>',
    'reward' => '<string>',
    'report' => '<string>',
    'pages' => [
        [
                'title' => '<string>',
                'content' => '<string>'
        ]
    ],
    'items' => [
        [
                'question' => '<string>',
                'answer' => '<string>',
                'choices' => [
                                '<string>'
                ],
                'context' => '<string>',
                'group' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.benchgen.com/api/competitions/{id}/edit_spec/"

	payload := strings.NewReader("{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.benchgen.com/api/competitions/{id}/edit_spec/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.benchgen.com/api/competitions/{id}/edit_spec/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "valid": true,
  "id": 123,
  "title": "<string>",
  "slug": "<string>",
  "published": true,
  "changed": [
    "<string>"
  ],
  "kind": "<string>",
  "pages": 123,
  "items": 123,
  "tasks_updated": 123,
  "preview": [
    {}
  ]
}

{
  "valid": true,
  "errors": [
    "<string>"
  ]
}

{
  "code": "benchmark_has_runs",
  "detail": "<string>",
  "runs": {
    "finished_runs": 123,
    "active_runs": 123
  }
}

Benchmark creation

Edit a benchmark

Change an existing benchmark the same way create_from_spec creates one. Send any of title, description, terms, pages, contact_email, organization_name, reward, report and items; anything else is refused. Everything except items is documentation: it changes in place and stays editable however much has been run against the benchmark. pages are the benchmark’s markdown tabs, sent in display order. Both pages and items replace their whole list rather than being merged in, so send back the entries you want to keep. Sending items revalidates the whole list (5-2000 entries, the same rules as creation), rebuilds the question datasets and repoints the benchmark’s tasks at them. Questions can only be replaced while nothing has been run against the benchmark: a finished run’s score describes the questions it saw, and a run in flight would read a dataset that changed under it, so both answer 409 with a runs count and you should create a new benchmark instead. Editing never changes whether the benchmark is published, who it is shared with, or its phases. Only the creator and its collaborators may edit. Requires the benchmark:edit scope, which is narrower than benchmark:manage and cannot delete a benchmark, reshape its phases or mail its participants.

POST

api

competitions

{id}

edit_spec

Edit a benchmark from a JSON spec

curl --request POST \
  --url https://api.benchgen.com/api/competitions/{id}/edit_spec/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Unit Conversion Basics, revised",
  "description": "<string>",
  "terms": "<string>",
  "contact_email": "jsmith@example.com",
  "organization_name": "<string>",
  "reward": "<string>",
  "report": "<string>",
  "pages": [
    {
      "title": "<string>",
      "content": "<string>"
    }
  ],
  "items": [
    {
      "question": "<string>",
      "answer": "<string>",
      "choices": [
        "<string>"
      ],
      "context": "<string>",
      "group": "<string>"
    }
  ]
}
'

import requests

url = "https://api.benchgen.com/api/competitions/{id}/edit_spec/"

payload = {
    "title": "Unit Conversion Basics, revised",
    "description": "<string>",
    "terms": "<string>",
    "contact_email": "jsmith@example.com",
    "organization_name": "<string>",
    "reward": "<string>",
    "report": "<string>",
    "pages": [
        {
            "title": "<string>",
            "content": "<string>"
        }
    ],
    "items": [
        {
            "question": "<string>",
            "answer": "<string>",
            "choices": ["<string>"],
            "context": "<string>",
            "group": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: 'Unit Conversion Basics, revised',
    description: '<string>',
    terms: '<string>',
    contact_email: 'jsmith@example.com',
    organization_name: '<string>',
    reward: '<string>',
    report: '<string>',
    pages: [{title: '<string>', content: '<string>'}],
    items: [
      {
        question: '<string>',
        answer: '<string>',
        choices: ['<string>'],
        context: '<string>',
        group: '<string>'
      }
    ]
  })
};

fetch('https://api.benchgen.com/api/competitions/{id}/edit_spec/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.benchgen.com/api/competitions/{id}/edit_spec/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Unit Conversion Basics, revised',
    'description' => '<string>',
    'terms' => '<string>',
    'contact_email' => 'jsmith@example.com',
    'organization_name' => '<string>',
    'reward' => '<string>',
    'report' => '<string>',
    'pages' => [
        [
                'title' => '<string>',
                'content' => '<string>'
        ]
    ],
    'items' => [
        [
                'question' => '<string>',
                'answer' => '<string>',
                'choices' => [
                                '<string>'
                ],
                'context' => '<string>',
                'group' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.benchgen.com/api/competitions/{id}/edit_spec/"

	payload := strings.NewReader("{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.benchgen.com/api/competitions/{id}/edit_spec/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.benchgen.com/api/competitions/{id}/edit_spec/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Unit Conversion Basics, revised\",\n  \"description\": \"<string>\",\n  \"terms\": \"<string>\",\n  \"contact_email\": \"jsmith@example.com\",\n  \"organization_name\": \"<string>\",\n  \"reward\": \"<string>\",\n  \"report\": \"<string>\",\n  \"pages\": [\n    {\n      \"title\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"items\": [\n    {\n      \"question\": \"<string>\",\n      \"answer\": \"<string>\",\n      \"choices\": [\n        \"<string>\"\n      ],\n      \"context\": \"<string>\",\n      \"group\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "valid": true,
  "id": 123,
  "title": "<string>",
  "slug": "<string>",
  "published": true,
  "changed": [
    "<string>"
  ],
  "kind": "<string>",
  "pages": 123,
  "items": 123,
  "tasks_updated": 123,
  "preview": [
    {}
  ]
}

{
  "valid": true,
  "errors": [
    "<string>"
  ]
}

{
  "code": "benchmark_has_runs",
  "detail": "<string>",
  "runs": {
    "finished_runs": 123,
    "active_runs": 123
  }
}

Authorizations

Authorization

string

header

required

Platform API token created under Profile Settings > Platform API tokens. Scopes are fixed at creation.

Path Parameters

integer

required

Benchmark id

Query Parameters

dry_run

boolean

Validate only: answers 200 with a summary and a preview, and changes nothing

Body

application/json

At least one of title, description, terms, pages, contact_email, organization_name, reward, report or items

title

string

Example:

"Unit Conversion Basics, revised"

description

string

terms

string

contact_email

string<email>

organization_name

string

Maximum string length: 256

reward

string

Maximum string length: 256

report

string

Maximum string length: 256

pages

object[]

The complete new page list, in display order, replacing the old one

Maximum array length: 20

Show child attributes

type

enum<string>

Optional and only together with items; inferred from the items when omitted

Available options:

question_answer,

multiple_choice

items

object[]

The complete new question list, replacing the old one

Required array length: 5 - 2000 elements

Show child attributes

Response

Edited, or with dry_run the summary of what would change

valid

boolean

integer

title

string

slug

string

published

boolean

changed

string[]

Which of title, description and items actually changed

kind

string

Present when items were sent

pages

integer | null

How many pages were sent, null when the edit left them alone

items

integer | null

How many items were sent, null when the edit left the questions alone

tasks_updated

integer

How many tasks got the rebuilt datasets

preview

object[]

dry_run only: the first few items as the platform read them

Last modified on September 16, 2026

API documentation

Authentication and tokens

Git repositories

Public endpoints

Benchmark creation

Benchmark runs

Fine-tuning and serving

Agents

Knowledge data

Billing

Edit a benchmark

Authorizations

Path Parameters

Query Parameters

Body

Response