This document provides detailed information about all available API endpoints.
http://localhost:8080
- Build Management
- Repository Management
- Pipeline Management
- GitHub Actions Integration
- Error Responses
Retrieve all builds in the system.
Endpoint: GET /api/builds
Response: 200 OK
[
{
"id": 1,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "SUCCESS",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": "2025-10-25T10:45:00"
},
{
"id": 2,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "IN_PROGRESS",
"commitSha": "b2c3d4e5f6g7...",
"startedAt": "2025-10-25T11:00:00",
"completedAt": null
}
]Retrieve details of a specific build.
Endpoint: GET /api/builds/{id}
Parameters:
id(path) - Build ID
Response: 200 OK
{
"id": 1,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "SUCCESS",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": "2025-10-25T10:45:00"
}Error Responses:
404 Not Found- Build not found
Retrieve all builds for a specific repository.
Endpoint: GET /api/builds/repository/{repositoryId}
Parameters:
repositoryId(path) - Repository ID
Response: 200 OK
[
{
"id": 1,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "SUCCESS",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": "2025-10-25T10:45:00"
}
]Retrieve all builds with a specific status.
Endpoint: GET /api/builds/status/{status}
Parameters:
status(path) - Build status (PENDING, IN_PROGRESS, SUCCESS, FAILED, CANCELLED)
Example:
curl http://localhost:8080/api/builds/status/SUCCESSResponse: 200 OK
[
{
"id": 1,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "SUCCESS",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": "2025-10-25T10:45:00"
}
]Error Responses:
400 Bad Request- Invalid status value
Trigger synchronization of workflow runs from GitHub Actions API to the database.
Endpoint: POST /api/builds/sync
Request Body:
{
"owner": "microsoft",
"repo": "vscode",
"repositoryId": 1
}Fields:
owner(required) - GitHub repository ownerrepo(required) - GitHub repository namerepositoryId(required) - Local database repository ID
Response: 200 OK
{
"success": true,
"syncedCount": 15,
"message": "Successfully synced 15 builds from GitHub",
"repositoryName": "backend-api"
}Error Responses:
400 Bad Request- Invalid request or repository not found
{
"success": false,
"syncedCount": 0,
"message": "Repository not found with ID: 1",
"repositoryName": null
}401 Unauthorized- Invalid GitHub token
{
"success": false,
"syncedCount": 0,
"message": "GitHub API error: Invalid authentication token",
"repositoryName": null
}404 Not Found- Repository not found on GitHub
{
"success": false,
"syncedCount": 0,
"message": "GitHub API error: Repository not found",
"repositoryName": null
}Example:
curl -X POST http://localhost:8080/api/builds/sync \
-H "Content-Type: application/json" \
-d '{
"owner": "microsoft",
"repo": "vscode",
"repositoryId": 1
}'Create a new build manually.
Endpoint: POST /api/builds?repositoryId={repositoryId}
Parameters:
repositoryId(query) - Repository ID
Request Body:
{
"status": "PENDING",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00"
}Response: 201 Created
{
"id": 3,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "PENDING",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": null
}Error Responses:
400 Bad Request- Invalid request or repository not found
Update an existing build.
Endpoint: PUT /api/builds/{id}
Parameters:
id(path) - Build ID
Request Body:
{
"status": "SUCCESS",
"completedAt": "2025-10-25T10:45:00"
}Response: 200 OK
{
"id": 1,
"repositoryId": 1,
"repositoryName": "backend-api",
"status": "SUCCESS",
"commitSha": "a1b2c3d4e5f6...",
"startedAt": "2025-10-25T10:30:00",
"completedAt": "2025-10-25T10:45:00"
}Error Responses:
404 Not Found- Build not found
Delete a build.
Endpoint: DELETE /api/builds/{id}
Parameters:
id(path) - Build ID
Response: 204 No Content
Error Responses:
404 Not Found- Build not found
Endpoint: GET /api/repositories
Response: 200 OK
[
{
"id": 1,
"name": "backend-api",
"githubUrl": "https://github.com/example/backend-api",
"createdAt": "2025-10-25T09:00:00"
}
]Endpoint: POST /api/repositories
Request Body:
{
"name": "my-app",
"githubUrl": "https://github.com/myorg/my-app"
}Response: 201 Created
{
"id": 1,
"name": "my-app",
"githubUrl": "https://github.com/myorg/my-app",
"createdAt": "2025-10-25T10:00:00"
}githubUrl may also be owner/repo shorthand, and name is optional (defaults to owner/repo). Workflow runs are synced right away. Returns 400 if the repository is already monitored or doesn't exist on GitHub.
Endpoint: GET /api/repositories/summary
Returns every repository with its latest build, its last 10 builds (newest first), and the success rate across the finished ones.
[
{
"repository": { "id": 1, "name": "angular/angular-cli", "githubUrl": "https://github.com/angular/angular-cli", "createdAt": "2026-10-21T20:59:55" },
"latestBuild": { "id": 12, "status": "IN_PROGRESS", "workflowName": "CI", "branch": "main", "commitSha": "3db6585...", "commitMessage": "build: update dependencies", "authorName": "Angular Robot", "htmlUrl": "https://github.com/angular/angular-cli/actions/runs/39674381174", "startedAt": "2026-10-21T20:54:44", "completedAt": null },
"recentBuilds": [ "..." ],
"successRate": 89
}
]All timestamps are UTC.
Endpoint: POST /api/repositories/{id}/sync
Response: 200 OK with a SyncResponse (syncedCount = builds created or updated).
Endpoint: DELETE /api/repositories/{id}
Stops monitoring the repository and deletes its builds. Response: 204 No Content
Endpoint: GET /api/pipelines
Endpoint: GET /api/pipelines/{id}
Endpoint: POST /api/pipelines
Request Body:
{
"name": "my-app-pipeline",
"description": "Main application build pipeline",
"repository": "https://github.com/example/my-app",
"branch": "main",
"status": "PENDING"
}Endpoint: GET /api/github/status/{owner}/{repo}
Example:
curl http://localhost:8080/api/github/status/microsoft/vscodeResponse: 200 OK
{
"runId": 1234567890,
"repositoryName": "vscode",
"branch": "main",
"commitSha": "abc123...",
"status": "completed",
"conclusion": "success",
"runNumber": 1234,
"startedAt": "2025-10-25T10:30:00",
"updatedAt": "2025-10-25T10:45:00",
"htmlUrl": "https://github.com/microsoft/vscode/actions/runs/1234567890",
"commitMessage": "Fix build issue",
"authorName": "John Doe"
}For more details, see GITHUB_INTEGRATION.md.
All error responses follow a consistent format:
{
"timestamp": "2025-10-25T10:30:00",
"status": 400,
"error": "Bad Request",
"message": "Repository not found with ID: 999",
"path": "/api/builds/sync",
"details": []
}Fields:
timestamp- When the error occurredstatus- HTTP status codeerror- HTTP status textmessage- Detailed error messagepath- Request path that caused the errordetails- Additional error details (for validation errors)
| Status Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid credentials |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 500 | Internal Server Error - Server error |
{
"timestamp": "2025-10-25T10:30:00",
"status": 400,
"error": "Validation Failed",
"message": "Invalid request parameters",
"path": "/api/builds/sync",
"details": [
"owner: must not be blank",
"repositoryId: must not be null"
]
}| Status | Description |
|---|---|
| PENDING | Build is queued |
| IN_PROGRESS | Build is currently running |
| SUCCESS | Build completed successfully |
| FAILED | Build failed |
| CANCELLED | Build was cancelled |
# Get all builds
curl http://localhost:8080/api/builds
# Get build by ID
curl http://localhost:8080/api/builds/1
# Get builds by status
curl http://localhost:8080/api/builds/status/SUCCESS
# Sync builds from GitHub
curl -X POST http://localhost:8080/api/builds/sync \
-H "Content-Type: application/json" \
-d '{
"owner": "microsoft",
"repo": "vscode",
"repositoryId": 1
}'
# Create a build
curl -X POST "http://localhost:8080/api/builds?repositoryId=1" \
-H "Content-Type: application/json" \
-d '{
"status": "PENDING",
"commitSha": "abc123def456",
"startedAt": "2025-10-25T10:30:00"
}'- Import the endpoints from this documentation
- Set base URL to
http://localhost:8080 - For POST requests, set
Content-Type: application/jsonheader - For GitHub integration, ensure
GITHUB_TOKENenvironment variable is set
# Get all builds
http GET :8080/api/builds
# Sync builds
http POST :8080/api/builds/sync \
owner=microsoft \
repo=vscode \
repositoryId:=1Currently, there are no rate limits on the local API endpoints. However, GitHub API has rate limits:
- Authenticated requests: 5,000 per hour
- Unauthenticated requests: 60 per hour
See GITHUB_INTEGRATION.md for more details on GitHub API limits.
Currently, the API does not require authentication. In production, consider implementing:
- JWT-based authentication
- API key authentication
- OAuth 2.0
For questions or issues, please refer to the main README.md or contact the development team.