OpenAPI specification for the Build Server API
GET /api/projects - Get projects for an accountPOST /api/projects - Create a new projectGET /api/projects/{id}/workflows - Get workflows for a projectPOST /api/projects/{id}/workflows - Create a new workflowGET /api/projects/{id}/builds - Get builds for a projectPOST /api/projects/{id}/builds - Create a new buildGET /api/docker-images - Get docker imagesPOST /api/docker-images - Create a new docker imageGET /api/runner/{stepId} - Get build step scriptPOST /api/runner/{stepId}/complete - Complete a build stepGET /api/audit-logs - Get audit logs{
"openapi": "3.0.0",
"info": {
"title": "Build Server API",
"version": "1.0.0",
"description": "API for managing build workflows, projects, and build execution",
"contact": {
"name": "Build Server Team"
}
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Development server"
}
],
"paths": {
"/api/projects": {
"get": {
"summary": "Get projects for an account",
"description": "Retrieves all projects for the specified account",
"tags": [
"Projects"
],
"parameters": [
{
"in": "query",
"name": "accountId",
"required": true,
"schema": {
"type": "string"
},
"description": "Account identifier to filter projects"
}
],
"responses": {
"200": {
"description": "List of projects",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
}
}
}
},
"400": {
"description": "Missing accountId parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new project",
"description": "Creates a new project for the specified account",
"tags": [
"Projects"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"accountId",
"name"
],
"properties": {
"accountId": {
"type": "string",
"description": "Account identifier",
"minLength": 1
},
"name": {
"type": "string",
"description": "Project name",
"minLength": 1,
"maxLength": 100
}
}
}
}
}
},
"responses": {
"201": {
"description": "Project created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Project"
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/projects/{id}/workflows": {
"get": {
"summary": "Get workflows for a project",
"description": "Retrieves all workflows for the specified project",
"tags": [
"Workflows"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Project identifier"
}
],
"responses": {
"200": {
"description": "List of workflows",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Workflow"
}
}
}
}
},
"404": {
"description": "Project not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new workflow",
"description": "Creates a new workflow for the specified project",
"tags": [
"Workflows"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Project identifier"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"steps"
],
"properties": {
"name": {
"type": "string",
"description": "Workflow name",
"minLength": 1,
"maxLength": 100
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"imageSlug",
"dependsOn",
"runScript",
"cacheDirs",
"outputPaths"
],
"properties": {
"name": {
"type": "string",
"description": "Step name",
"minLength": 1,
"maxLength": 100
},
"imageSlug": {
"type": "string",
"description": "Docker image slug",
"minLength": 1
},
"dependsOn": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of step names this step depends on"
},
"runScript": {
"type": "string",
"description": "Script to run in this step",
"minLength": 1
},
"cacheDirs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Directories to cache between builds"
},
"outputPaths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Paths to artifacts to preserve"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Workflow created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workflow"
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Project not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/projects/{id}/builds": {
"get": {
"summary": "Get builds for a project",
"description": "Retrieves builds for the specified project with pagination",
"tags": [
"Builds"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Project identifier"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 20
},
"description": "Maximum number of builds to return"
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"default": 0
},
"description": "Number of builds to skip"
}
],
"responses": {
"200": {
"description": "List of builds with pagination info",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"builds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Build"
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of builds"
},
"limit": {
"type": "integer",
"description": "Number of builds per page"
},
"offset": {
"type": "integer",
"description": "Number of builds skipped"
},
"hasMore": {
"type": "boolean",
"description": "Whether there are more builds available"
}
}
}
}
}
}
}
},
"404": {
"description": "Project not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new build",
"description": "Creates a new build for the specified project using a workflow",
"tags": [
"Builds"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Project identifier"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"workflowId"
],
"properties": {
"workflowId": {
"type": "string",
"description": "Workflow identifier to use for this build",
"minLength": 1
},
"commitHash": {
"type": "string",
"description": "Git commit hash"
},
"repoUrl": {
"type": "string",
"format": "uri",
"description": "Git repository URL"
},
"branch": {
"type": "string",
"description": "Git branch name"
},
"commitMessage": {
"type": "string",
"description": "Git commit message"
},
"commitAuthor": {
"type": "string",
"description": "Git commit author"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Build created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Build"
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Project or workflow not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/docker-images": {
"get": {
"summary": "Get docker images",
"description": "Retrieves all docker images, optionally filtered to public only",
"tags": [
"Docker Images"
],
"parameters": [
{
"in": "query",
"name": "public",
"schema": {
"type": "boolean"
},
"description": "Filter to public images only"
}
],
"responses": {
"200": {
"description": "List of docker images",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DockerImage"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a new docker image",
"description": "Creates a new docker image that can be used in workflows",
"tags": [
"Docker Images"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"slug",
"imageUrl"
],
"properties": {
"slug": {
"type": "string",
"description": "Unique slug for the docker image",
"minLength": 1,
"maxLength": 50
},
"imageUrl": {
"type": "string",
"format": "uri",
"description": "Docker image URL"
},
"public": {
"type": "boolean",
"default": false,
"description": "Whether the image is publicly available"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Docker image created successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DockerImage"
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Docker image with this slug already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/runner/{stepId}": {
"get": {
"summary": "Get build step script",
"description": "Generates and returns the bash script for a build step that workers will execute",
"tags": [
"Runner"
],
"parameters": [
{
"in": "path",
"name": "stepId",
"required": true,
"schema": {
"type": "string"
},
"description": "Build step identifier"
}
],
"responses": {
"200": {
"description": "Bash script for the build step",
"content": {
"text/plain": {
"schema": {
"type": "string",
"description": "Bash script to execute"
}
}
}
},
"404": {
"description": "Step not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/runner/{stepId}/complete": {
"post": {
"summary": "Complete a build step",
"description": "Marks a build step as completed and updates the build status",
"tags": [
"Runner"
],
"parameters": [
{
"in": "path",
"name": "stepId",
"required": true,
"schema": {
"type": "string"
},
"description": "Build step identifier"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"success",
"failed"
],
"description": "Step completion status"
},
"logs": {
"type": "string",
"description": "Step execution logs"
},
"outputPaths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Path to artifacts generated by this step"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Step completed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether the operation was successful"
},
"stepStatus": {
"type": "string",
"description": "Updated step status"
},
"buildComplete": {
"type": "boolean",
"description": "Whether all steps in the build are complete"
}
}
}
}
}
},
"400": {
"description": "Invalid request data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Step not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/audit-logs": {
"get": {
"summary": "Get audit logs",
"description": "Retrieves audit logs with optional filtering and pagination",
"tags": [
"Audit"
],
"parameters": [
{
"in": "query",
"name": "projectId",
"schema": {
"type": "string"
},
"description": "Filter logs by project ID"
},
{
"in": "query",
"name": "action",
"schema": {
"type": "string"
},
"description": "Filter logs by action type"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 100
},
"description": "Maximum number of logs to return"
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"default": 0
},
"description": "Number of logs to skip"
}
],
"responses": {
"200": {
"description": "List of audit logs with pagination info",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"auditLogs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AuditLog"
}
},
"pagination": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of logs"
},
"limit": {
"type": "integer",
"description": "Number of logs per page"
},
"offset": {
"type": "integer",
"description": "Number of logs skipped"
},
"hasMore": {
"type": "boolean",
"description": "Whether there are more logs available"
}
}
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique project identifier"
},
"accountId": {
"type": "string",
"description": "Account that owns the project"
},
"name": {
"type": "string",
"description": "Project name"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
},
"Workflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique workflow identifier"
},
"projectId": {
"type": "string",
"description": "Project this workflow belongs to"
},
"name": {
"type": "string",
"description": "Workflow name"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
},
"Build": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique build identifier"
},
"projectId": {
"type": "string",
"description": "Project this build belongs to"
},
"workflowId": {
"type": "string",
"description": "Workflow used for this build"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"RUNNING",
"SUCCESS",
"FAILED"
],
"description": "Current build status"
},
"commitHash": {
"type": "string",
"description": "Git commit hash"
},
"repoUrl": {
"type": "string",
"description": "Git repository URL"
},
"branch": {
"type": "string",
"description": "Git branch name"
},
"commitMessage": {
"type": "string",
"description": "Git commit message"
},
"commitAuthor": {
"type": "string",
"description": "Git commit author"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"finishedAt": {
"type": "string",
"format": "date-time"
}
}
},
"DockerImage": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique docker image identifier"
},
"slug": {
"type": "string",
"description": "Unique slug for the docker image"
},
"imageUrl": {
"type": "string",
"description": "Docker image URL"
},
"public": {
"type": "boolean",
"description": "Whether the image is publicly available"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
"AuditLog": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique audit log identifier"
},
"projectId": {
"type": "string",
"description": "Project this log entry belongs to"
},
"action": {
"type": "string",
"description": "Action that was performed"
},
"details": {
"type": "object",
"description": "Additional details about the action"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message"
},
"details": {
"type": "array",
"items": {
"type": "object"
},
"description": "Validation error details"
}
}
}
},
"securitySchemes": {}
},
"tags": [
{
"name": "Projects",
"description": "Project management operations"
},
{
"name": "Workflows",
"description": "Workflow management operations"
},
{
"name": "Builds",
"description": "Build execution operations"
},
{
"name": "Docker Images",
"description": "Docker image management"
},
{
"name": "Runner",
"description": "Build runner operations"
},
{
"name": "Audit",
"description": "Audit log operations"
}
]
}