Specs REST API

List specs

โš ๏ธ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

โž• Bencher Plus: List all hardware specs on the server. The user must be an admin to use this endpoint.

Headers

Content-Type

string

Required

Set to application/json.

Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Query Parameters

direction

string

The direction to sort by. If not specified, the default sort direction is used.

Default: asc

One of: asc, desc

page

integer

The page number to return. If not specified, the first page is returned.

Default: 1

per_page

integer

The number of items to return per page. If not specified, the default number of items per page (8) is used.

Default: 8

sort

string

The field to sort by. If not specified, the default sort field is used.

One of: name, created

archived

boolean

Include archived specs.

name

string

Filter by spec name, exact match.

search

string

Search by spec name, slug, or UUID.

GET
/v0/specs
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher spec list

View OpenAPI Spec

Create a spec

โš ๏ธ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

โž• Bencher Plus: Create a new hardware spec on the server. The user must be an admin to use this endpoint.

Headers

Content-Type

string

Required

Set to application/json.

Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Body Parameters

architecture

string

Required

CPU architecture

One of: x86_64, aarch64

cpu

integer

Required

Number of CPUs

disk

integer

Required

Disk size in bytes

memory

integer

Required

Memory size in bytes

name

string

Required

The name of the spec.

network

boolean

Required

Whether the VM has network access

slug

The preferred slug for the spec. If not provided, the slug will be generated from the name.

POST
/v0/specs
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher spec create

View OpenAPI Spec

View a spec

โš ๏ธ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

โž• Bencher Plus: View a hardware spec on the server. The user must be an admin to use this endpoint.

Headers

Content-Type

string

Required

Set to application/json.

Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters

spec
Required

The UUID or slug for a spec.

GET
/v0/specs/{spec}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher spec view SPEC

View OpenAPI Spec

Update a spec

โš ๏ธ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

โž• Bencher Plus: Update a hardware spec on the server. The user must be an admin to use this endpoint.

Headers

Content-Type

string

Required

Set to application/json.

Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters

spec
Required

The UUID or slug for a spec.

Body Parameters

archived

boolean

Set whether the spec is archived.

name

string

The new name for the spec.

slug

The new slug for the spec.

PATCH
/v0/specs/{spec}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher spec update SPEC

View OpenAPI Spec

Delete a spec

โš ๏ธ Breaking Changes: The Bencher API is in beta and under active development. We may introduce breaking changes in future releases. We will announce any breaking changes in the release notes.

โž• Bencher Plus: Delete a hardware spec from the server. The user must be an admin to use this endpoint. Returns 409 Conflict if the spec is referenced by runners or jobs.

Headers

Content-Type

string

Required

Set to application/json.

Authorization

string

Required

Set to Bearer BENCHER_API_TOKEN, where BENCHER_API_TOKEN is a vaild Bencher API token.

Path Parameters

spec
Required

The UUID or slug for a spec.

DELETE
/v0/specs/{spec}
Bencher Cloud https://api.bencher.dev
Bencher Self-Hosted http://localhost:61016

Bencher CLI

bencher spec delete SPEC

View OpenAPI Spec

Published: Mon, February 12, 2024 at 7:26:00 AM UTC | Last Updated: Sun, December 7, 2025 at 5:47:00 PM UTC