API Endpoints

Complete reference for the BuildButler REST API — jobs, builds, analytics, and connections.

The BuildButler API is a RESTful JSON API. All endpoints are prefixed with /api/v1.

Base URL

https://buildbutler.example.com/api/v1

Jobs

List jobs

GET /api/v1/jobs

Query parameters:

Parameter	Type	Description
`instance`	`string`	Filter by Jenkins instance name
`folder`	`string`	Filter by Jenkins folder path
`page`	`number`	Page number (default: 1)
`per_page`	`number`	Items per page (default: 25, max: 100)

Response:

{
  "data": [
    {
      "id": "j_abc123",
      "name": "production-deploy",
      "instance": "Production",
      "folder": "/pipelines",
      "lastBuild": 42,
      "lastResult": "SUCCESS",
      "successRate": 0.94
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 156
  }
}

Get job details

GET /api/v1/jobs/:id

Builds

List builds for a job

GET /api/v1/jobs/:jobId/builds

Query parameters:

Parameter	Type	Description
`result`	`string`	Filter by result: `SUCCESS`, `FAILURE`, `UNSTABLE`, `ABORTED`
`branch`	`string`	Filter by branch name
`since`	`ISO 8601`	Builds after this timestamp
`until`	`ISO 8601`	Builds before this timestamp

Get build details

GET /api/v1/builds/:id

Response:

{
  "id": "b_xyz789",
  "jobId": "j_abc123",
  "number": 42,
  "result": "FAILURE",
  "duration": 184000,
  "queueTime": 12000,
  "timestamp": "2025-01-15T10:32:00Z",
  "branch": "main",
  "commit": "a1b2c3d",
  "failureCategory": "test_failure",
  "stages": [
    { "name": "Checkout", "duration": 3000, "result": "SUCCESS" },
    { "name": "Build", "duration": 45000, "result": "SUCCESS" },
    { "name": "Test", "duration": 136000, "result": "FAILURE" }
  ]
}

Get build log

GET /api/v1/builds/:id/log

Returns the raw console output as text/plain.

Analytics

Aggregate metrics

GET /api/v1/analytics/metrics

Query parameters:

Parameter	Type	Description
`range`	`string`	`24h`, `7d`, `30d`, or custom ISO range
`job`	`string`	Filter to a specific job ID
`group_by`	`string`	`job`, `folder`, `label`, or `branch`

Response:

{
  "successRate": 0.92,
  "avgDuration": 142000,
  "p95Duration": 310000,
  "avgQueueTime": 8500,
  "totalBuilds": 1247
}

Export data

GET /api/v1/analytics/export

Parameter	Type	Description
`format`	`string`	`csv`, `json`, or `png`
`range`	`string`	Time range
`job`	`string`	Job filter

Connections

List connections

GET /api/v1/connections

Create a connection

POST /api/v1/connections
Content-Type: application/json
 
{
  "name": "Production Jenkins",
  "url": "https://jenkins.example.com",
  "username": "ci-bot",
  "token": "your-api-token"
}

Delete a connection

DELETE /api/v1/connections/:id

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "details": {}
  }
}

Status	Code	Description
400	`bad_request`	Invalid request parameters
401	`unauthorized`	Missing or invalid authentication
403	`forbidden`	Insufficient permissions
404	`not_found`	Resource not found
429	`rate_limited`	Too many requests
500	`internal_error`	Server error

API Endpoints

On this page