API Reference

The gitlab-summary serve command exposes a REST API for integration with other tools and custom dashboards.

Base URL

When running locally:

  http://localhost:5100

With custom port:

  http://localhost:<PORT>

Core Endpoints

GET /api/health

Health check endpoint.

Response:

  {
  "status": "healthy",
  "timestamp": "2024-02-08T16:25:23Z"
}

GET /api/version

Version information.

Response:

  {
  "version": "1.0.0",
  "gitCommit": "abc123def",
  "buildDate": "2024-02-08"
}

Pipeline Endpoints

GET /api/events/pipelines

Server-Sent Events stream of pipeline summaries.

Headers:

  Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Event Format:

  event: pipeline-update
data: {"projects":[...],"summary":{...}}

event: heartbeat
data: {"timestamp":"2024-02-08T16:25:23Z"}

Example (JavaScript):

  const eventSource = new EventSource('/api/events/pipelines');

eventSource.addEventListener('pipeline-update', (event) => {
  const data = JSON.parse(event.data);
  console.log('Projects:', data.projects);
  console.log('Summary:', data.summary);
});

GET /api/pipelines/summary

Current pipeline summary snapshot (non-streaming).

Response:

  {
  "projects": [
    {
      "project_id": 123,
      "project_name": "api-service",
      "total_pipelines": 45,
      "successful": 42,
      "failed": 2,
      "running": 1,
      "total_duration": 750,
      "success_rate": 93.3,
      "recent_pipelines": [...]
    }
  ],
  "summary": {
    "total_pipelines": 126,
    "successful": 118,
    "failed": 6,
    "running": 2,
    "average_duration": 308,
    "overall_success_rate": 93.7
  }
}

GET /api/pipelines/{projectId}/details/{pipelineId}

Pipeline and job details for a specific pipeline.

Parameters:

  • projectId — GitLab project ID (integer)
  • pipelineId — GitLab pipeline ID (integer)

Response:

  {
  "pipeline_id": 12345,
  "project_id": 123,
  "status": "failed",
  "ref": "main",
  "source": "push",
  "created_at": "2024-02-08T10:00:00Z",
  "started_at": "2024-02-08T10:01:00Z",
  "finished_at": "2024-02-08T10:08:30Z",
  "duration": 450,
  "user": {
    "id": 456,
    "username": "jdoe",
    "name": "John Doe",
    "avatar_url": "https://..."
  },
  "commit": {
    "id": "abc123",
    "short_id": "abc123",
    "title": "fix: update API endpoint",
    "message": "fix: update API endpoint\n\nDetailed description...",
    "author_name": "John Doe",
    "author_email": "jdoe@example.com",
    "created_at": "2024-02-08T09:55:00Z"
  },
  "jobs": [
    {
      "id": 789,
      "name": "build",
      "stage": "build",
      "status": "success",
      "created_at": "2024-02-08T10:01:00Z",
      "started_at": "2024-02-08T10:01:30Z",
      "finished_at": "2024-02-08T10:03:00Z",
      "duration": 90
    },
    {
      "id": 790,
      "name": "test",
      "stage": "test",
      "status": "failed",
      "created_at": "2024-02-08T10:03:05Z",
      "started_at": "2024-02-08T10:03:10Z",
      "finished_at": "2024-02-08T10:08:20Z",
      "duration": 310
    }
  ]
}

Settings Endpoints

GET /api/settings

Get current group and time period settings.

Response:

  {
  "group": "my-org",
  "since": "7d",
  "gitlabUrl": "https://gitlab.example.com"
}

POST /api/settings

Update group and/or time period dynamically.

Request Body:

  {
  "group": "different-org",
  "since": "3d"
}

Response:

  {
  "success": true,
  "group": "different-org",
  "since": "3d"
}

Group Hierarchy Endpoints

GET /api/groups/{groupIdOrPath}

Get group details.

Parameters:

  • groupIdOrPath — GitLab group ID or path

Response:

  {
  "id": 123,
  "name": "My Organization",
  "path": "my-org",
  "full_path": "parent/my-org",
  "description": "Organization description",
  "visibility": "private",
  "parent_id": 100
}

GET /api/groups/{groupIdOrPath}/subgroups

Get child groups (subgroups).

Parameters:

  • groupIdOrPath — GitLab group ID or path

Response:

  [
  {
    "id": 124,
    "name": "Backend",
    "path": "backend",
    "full_path": "my-org/backend"
  },
  {
    "id": 125,
    "name": "Frontend",
    "path": "frontend",
    "full_path": "my-org/frontend"
  }
]

GET /api/groups/parent/{parentId}

Get sibling groups by parent ID.

Parameters:

  • parentId — Parent group ID

Response:

  [
  {
    "id": 123,
    "name": "My Organization",
    "path": "my-org"
  },
  {
    "id": 126,
    "name": "Other Organization",
    "path": "other-org"
  }
]

AI Analysis Endpoints

POST /api/ai/analyse

Analyze a failed job with GitHub Copilot.

Request Body:

  {
  "projectId": 123,
  "pipelineId": 12345,
  "jobId": 789,
  "jobName": "test",
  "stage": "test",
  "log": "optional job log content"
}

Response:

  {
  "analysis": "The test failed because...\n\nRoot cause:\n...\n\nRecommended fix:\n...",
  "cached": false,
  "timestamp": "2024-02-08T16:25:23Z"
}

POST /api/ai/followup

Ask a follow-up question about a previous analysis.

Request Body:

  {
  "projectId": 123,
  "pipelineId": 12345,
  "jobId": 789,
  "jobName": "test",
  "stage": "test",
  "question": "How can I fix this locally?",
  "log": "optional job log",
  "previousAnalysis": "previous analysis text"
}

Response:

  {
  "answer": "To fix this locally...",
  "timestamp": "2024-02-08T16:26:00Z"
}

GET /api/ai/analyzed

Get list of analyzed job IDs for a project.

Query Parameters:

  • projectId — GitLab project ID

Response:

  {
  "projectId": 123,
  "analyzedJobIds": [789, 790, 791]
}

GET /api/ai/cache

Get cached analysis for a specific job.

Query Parameters:

  • projectId — GitLab project ID
  • jobId — GitLab job ID

Response:

  {
  "projectId": 123,
  "pipelineId": 12345,
  "jobId": 789,
  "jobName": "test",
  "stage": "test",
  "analysis": "Initial analysis...",
  "conversation": [
    {
      "question": "How to fix?",
      "answer": "...",
      "timestamp": "2024-02-08T16:26:00Z"
    }
  ],
  "timestamp": "2024-02-08T16:25:23Z"
}

DELETE /api/ai/cache

Delete cached analysis.

Query Parameters:

  • projectId — GitLab project ID
  • jobId — GitLab job ID

Response:

  {
  "success": true,
  "message": "Analysis deleted successfully"
}

GET /api/ai/history

Get paginated list of all cached analyses.

Query Parameters:

  • page — Page number (default: 1)
  • pageSize — Results per page (default: 20, max: 100)

Response:

  {
  "analyses": [
    {
      "projectId": 123,
      "projectName": "api-service",
      "pipelineId": 12345,
      "jobId": 789,
      "jobName": "test",
      "stage": "test",
      "analysis": "...",
      "conversationCount": 2,
      "timestamp": "2024-02-08T16:25:23Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95
  }
}

GET /api/ai/system-prompt

Get current AI system prompt.

Response:

  {
  "prompt": "You are an expert CI/CD troubleshooter..."
}

PUT /api/ai/system-prompt

Update AI system prompt.

Request Body:

  {
  "prompt": "Custom system prompt..."
}

Response:

  {
  "success": true,
  "prompt": "Custom system prompt..."
}

Job Trace Endpoint

GET /api/jobtrace

Get job log trace.

Query Parameters:

  • projectId — GitLab project ID
  • jobId — GitLab job ID

Response:

  {
  "trace": "$ npm install\nInstalling dependencies...\n...",
  "complete": true
}

Avatar Proxy

GET /api/avatar

Proxy endpoint for GitLab avatars (CORS workaround).

Query Parameters:

  • url — Full avatar URL from GitLab API

Response: Image binary data

Integration Examples

Python 

  import requests

# Get pipeline summary
response = requests.get('http://localhost:5100/api/pipelines/summary')
data = response.json()

for project in data['projects']:
    print(f"{project['project_name']}: {project['success_rate']}%")

JavaScript (Fetch) 

  // Get pipeline details
async function getPipelineDetails(projectId, pipelineId) {
  const response = await fetch(
    `/api/pipelines/${projectId}/details/${pipelineId}`
  );
  return await response.json();
}

const details = await getPipelineDetails(123, 12345);
console.log(details.jobs);

cURL 

  # Health check
curl http://localhost:5100/api/health

# Get summary
curl http://localhost:5100/api/pipelines/summary | jq .

# Change group
curl -X POST http://localhost:5100/api/settings \
  -H "Content-Type: application/json" \
  -d '{"group":"my-org","since":"7d"}'

# Get pipeline details
curl http://localhost:5100/api/pipelines/123/details/12345 | jq .

Error Responses

All endpoints return consistent error responses:

  {
  "error": "Error description",
  "statusCode": 400,
  "timestamp": "2024-02-08T16:25:23Z"
}

Common Status Codes:

  • 400 — Bad request (invalid parameters)
  • 401 — Unauthorized (invalid GitLab token)
  • 404 — Not found (pipeline, job, or group not found)
  • 500 — Internal server error

Rate Limiting

gitlab-summary respects GitLab API rate limits:

  • Public API: 300 requests per minute per IP
  • Authenticated: 2000 requests per minute per user

The tool automatically throttles requests to stay within limits.

See Also