Automation
Automate runner and runner images creation
AWS BYOC API Documentation
This page contains API call documentation to automate runner images and runner operations. This can be used to automate custom image builds, run a test suite on the new images, etc.
Notes
- It is recommended to remove unused custom runners. There can be an increase in the job pick up times, if a lot of runners are present.
Setup
Create a new API key
Go to the API keys page and create a new API key.
Grant the ci, and cache scopes to the API key.
Usage
Stacks
Get all stacks
curl -X GET 'https://api.warpbuild.com/api/v1/stacks?kind=ec2' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'Runner Images
Get all runner images
The alias parameter is optional. It is recommended to use the other search parameters (type, page, per_page) to filter the results.
curl -X GET 'https://api.warpbuild.com/api/v1/runner-images?alias=<image-name>&type=byoc_ami&page=1&per_page=10' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'Create a new BYOC runner image
You can fetch the stack_id from the GET /api/v1/stacks endpoint.
curl -X POST 'https://api.warpbuild.com/api/v1/runner-images' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'
-d @create-runner-image.json{
"alias": "test1",
"os": "linux",
"arch": "x64",
"stack_id": "wxxxxxx",
"type": "byoc_ami",
"warpbuild_image": {
"image_uri": "ami-xxxxxx",
"cloud_init_template": ""
},
"settings": {
"purge_image_versions_offset": 1
},
"byoc_ami": {
"ami_id": "ami-xxxxxx",
"root_device_name": "/dev/sda1"
}
}Update a BYOC runner image
You can fetch the id from
- the
GET /api/v1/runner-imagesendpoint with thealiasparameter. - As a response to the
POST /api/v1/runner-imagesendpoint when creating a new runner image.
curl -X PUT 'https://api.warpbuild.com/api/v1/runner-images/wxxxxxx' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx' \
-d @update-runner-image.json{
"byoc_ami": {
"ami_id": "ami-new-xxxxxx",
"root_device_name": "/dev/sda1"
},
"id": "wxxxxxx",
"settings": {
"purge_image_versions_offset": 1
}
}Runners
List runners
Returns the list of all available runners in the organization. This API call is not paginated.
Params
only_custom_runners: Boolean flag. Enable to list only custom runners. Accepted values -true,false.image: Image ID as filter. You can use the image id that is generated by the runner images API above. Example:wjwnpdjox8xeqsza.
Call
curl -X GET 'https://api.warpbuild.com/api/v1/runners?only_custom_runners=<bool>&image=<image-id>' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'Output is array of objects. The object structure follows the structure defined in create runner.
Get a runner
Returns a single runner based on its id.
Params
runner-id: The id for the runner.
Call
curl -X GET 'https://api.warpbuild.com/api/v1/runners/<runner-id>' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'Output structure is same as the create endpoint.
Create a runner
Params
name: Name of the runner must be lowercase alphabets with hyphen as additional characters.provider_id: Stack id of the runner.configuration.image: The image id from the runner images APIconfiguration.byoc_sku.role_arn: The instance role of the runner.configuration.byoc_sku.instance_types: List of instance/machine types that are to be used when launching the runner. Make sure you provide a valid list here. For a list of valid image types it is recommended to use the UI.
Additional params are captured below.
{
"name": "warpdev-custom-example-2",
"provider_id": "wrslzvbl322yttsc",
"pool_size": 2,
"configuration": {
"capacity_type": "ondemand",
"image": "wjwnpdjox8xeqsza",
"sku": "",
"storage": {
"disk_type": "",
"tier": "custom",
"performance_tier": "",
"size": 150,
"throughput": 400,
"iops": 6000
},
"byoc_sku": {
"instance_types": ["c3.large", "c1.xlarge"],
"is_public": true,
"arch": "x64",
"role_arn": "",
"network_tier": "STANDARD"
}
}
}Call
curl -X POST 'https://api.warpbuild.com/api/v1/runners' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx' \
-H 'Content-Type: application/json' \
-d @create-runner.json{
"id": "<runner-id>",
"created_at": "2025-09-25T08:38:01.495654Z",
"updated_at": "2025-09-25T08:38:01.495654Z",
"name": "warpdev-custom-example-2",
"vcs_integration_id": "<integration-id>",
"configuration": {
"sku": "",
"byoc_sku": {
"role_arn": "",
"arch": "x64",
"is_public": true,
"instance_types": [
"c3.large",
"c1.xlarge"
],
"network_tier": ""
},
"storage": {
"tier": "custom",
"size": 150,
"iops": 5000,
"throughput": 400,
"disk_type": "",
"performance_tier": ""
},
"image": "wjwnpdjox8xeqsza",
"capacity_type": "ondemand"
},
"stock_runner_id": null,
"organization_id": "<organization-id>",
"labels": [
"warpdev-custom-example-2"
],
"active": true,
"provider_id": "wrslzvbl322yttsc",
"meta": {
"supports_snapshot": false
}
}Update a runner
Update an existing runner.
Params
{
"pool_size": 2,
"labels": [],
"configuration": {
"image": "wjwnpdjox8xeqsza",
"capacity_type": "ondemand",
"sku": "",
"storage": {
"disk_type": "",
"tier": "custom",
"performance_tier": "",
"size": 150,
"throughput": 400,
"iops": 6000
},
"byoc_sku": {
"instance_types": ["c3.large", "c1.xlarge"],
"is_public": true,
"arch": "x64",
"network_tier": ""
}
}
}Call
curl -X PATCH 'https://api.warpbuild.com/api/v1/runners/<runner-id>' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx' \
-H 'Content-Type: application/json' \
-d @update-runner.jsonOutput structure is same as the create endpoint.
Delete a runner
Delete an existing runner. This action is irreversible.
Params
runner-id: The id for the runner to delete.
Call
curl -X DELETE 'https://api.warpbuild.com/api/v1/runners/<runner-id>' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer wkey-xxxx'Output structure is same as the create endpoint.
Last updated on