Cyclopt OpenAPI

Welcome to the Cyclopt API documentation! Before you dive in, please take a moment to check out the API Overview section.

General

General | API Overview

Welcome to the Cyclopt API! This guide provides an overview of the API's capabilities, including how to interact with various endpoints, authentication requirements, pagination controls, and handling of common response formats and errors.

Features:

  • Analyses: Retrieve detailed analysis data for commits, repositories by their ID, or by owner and repository name.
  • Projects: Access and manage project-specific information and tasks.
  • Repositories: Interact with repository data, including commit history and analytics.
  • Teams: Manage and retrieve detailed team information.

Authentication:

All endpoints require an authorization token to access. Ensure you include a valid token in the headers of your requests:

Pagination:

Many endpoints that return lists support pagination to manage data flow and optimize client-side data handling. Pagination is controlled via page and limit query parameters. Responses may include next and prev links to aid in navigation between results pages.

Base URL 
https://server.cyclopt.com/cyclopt/openapi

Authorization Header

Field Type Description
x-access-cyclopt-token required String

Authorization token required for accessing the API.

 
{
    "x-access-cyclopt-token": "abcdef12345"
}

Pagination Query Parameters

Field Type Description
page optional Number

The page number to access.

Default value: 1
limit optional Number

The maximum number of records to return per page.

Default value: 10

Success 200

Field Type Description
next required String

URL to the next page of results, if available.
prev required String

URL to the previous page of results, if available.

 
HTTP/1.1 400 Bad Request
{
  "error": "Invalid page number, must be 1 or greater."
}
HTTP/1.1 400 Bad Request
{
  "error": "Invalid limit, must be between 1 and 100."
}
HTTP/1.1 404 Not Found
{
  "error": "ResourceNotFound",
}

Analyses

Analyses | Retrieve Analyses by Repository Owner and Name

Retrieves all analyses for a specified repository, uniquely identified by the owner and repository name. This endpoint supports filtering by branch, language, and root directory.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

get 
/analyses/:OWNER/:NAME

URL Parameters

Field Type Description
OWNER required String

Owner's username or identifier, who owns the repository.
NAME required String

Repository's name for which analyses need to be fetched.

Query Parameter(s)

Field Type Description
branch optional String

Optional. Filter analyses based on the branch name.
language optional String

Optional. Filter analyses by the programming language.
root optional String

Optional. Filter analyses based on the repository's root directory.

Success 200

Field Type Description
user required Object

User details.
  username required String

The username of the user requesting the analysis.
  email required String

The email of the user requesting the analysis.
analyses required Object[]

Array of analysis objects, each representing a detailed analysis.
  language required String

Programming language of the code analyzed.
  root required String

Repository's root directory where the code resides.
  sha required String

Commit hash that was analyzed.
  branches required String[]

List of branches associated with the analyzed commit.
  characteristics required Object

Code characteristics such as maintainability, readability, reusability, and security scores.
  overallQualityScore required Number

Calculated overall quality score from the analysis.
  totalLocAnalyzed required Number

Total lines of code analyzed.
  totalViolationsCount required Number

Total number of violations found.
  violations required Object

Detailed counts of code violations categorized by severity (minor, major, critical).
  date required String

Date and time when the analysis was completed.
  metrics required Object

Detailed metrics of the code analyzed.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "analyses": [
    {
      "language": "Python",
      "root": "Repository root",
      "sha": "da80067a.....ac145a9a",
      "branches": ["main"],
      "characteristics": {
        "maintainabilityScore": 0.4,
        "readabilityScore": 0.55,
        "reusabilityScore": 0.65,
        "securityScore": 1
      },
      "overallQualityScore": 0.66,
      "totalLocAnalyzed": 3022,
      "totalViolationsCount": 24,
      "violations": {
        "minor": 0,
        "major": 3,
        "critical": 21
      },
      "date": "2020-05-15T09:30:00.000Z",
      "metrics": {
        "Physical Lines of Code": 3855,
        "Logical Lines of Code": 3337,
        "Dependency Vulnerabilities": 7,
        "Total Files": 201,
        "Maintainability Index": 118.516,
        "Cyclomatic Complexity": 1.03,
        "Effort (Days)": 469.69,
        "Comment Density (%)": 0.53,
        "Duplicate Code (%)": 18.55,
        "Function Count": 1579,
        "Avg LOC per Function": 2.76,
        "Class Count": 175,
        "Avg LOC per Class": 22.8
      }
    },
    // more analyses...
  ],
  "next": "http://base_url/analyses/:OWNER/:NAME?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RepositoryNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "CommitsNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "NoRepositoriesForThisToken."
}

Analyses | Retrieve Analyses by Repository ID

Request analysis by a specific REPOSITORY_ID.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

get 
/analyses/repository/:REPOSITORY_ID

URL Parameters

Field Type Description
REPOSITORY_ID required String

Repository's unique ID.

Success 200

Field Type Description
user required Object

User details.
  username required String

The username of the user requesting the analysis.
  email required String

The email of the user requesting the analysis.
analyses required Object[]

Array of analysis objects, each representing a detailed analysis.
  language required String

Programming language of the code analyzed.
  root required String

Repository's root directory where the code resides.
  sha required String

Commit hash that was analyzed.
  branches required String[]

List of branches associated with the analyzed commit.
  characteristics required Object

Code characteristics such as maintainability, readability, reusability, and security scores.
  overallQualityScore required Number

Calculated overall quality score from the analysis.
  totalLocAnalyzed required Number

Total lines of code analyzed.
  totalViolationsCount required Number

Total number of violations found.
  violations required Object

Detailed counts of code violations categorized by severity (minor, major, critical).
  date required String

Date and time when the analysis was completed.
  metrics required Object

Detailed metrics of the code analyzed.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "analyses": [
    {
      "language": "Python",
      "root": "Repository root",
      "sha": "da80067a.....ac145a9a",
      "branches": ["main"],
      "characteristics": {
        "maintainabilityScore": 0.4,
        "readabilityScore": 0.55,
        "reusabilityScore": 0.65,
        "securityScore": 1
      },
      "overallQualityScore": 0.66,
      "totalLocAnalyzed": 3022,
      "totalViolationsCount": 24,
      "violations": {
        "minor": 0,
        "major": 3,
        "critical": 21
      },
      "date": "2020-05-15T09:30:00.000Z",
      "metrics": {
        "Physical Lines of Code": 3855,
        "Logical Lines of Code": 3337,
        "Dependency Vulnerabilities": 7,
        "Total Files": 201,
        "Maintainability Index": 118.516,
        "Cyclomatic Complexity": 1.03,
        "Effort (Days)": 469.69,
        "Comment Density (%)": 0.53,
        "Duplicate Code (%)": 18.55,
        "Function Count": 1579,
        "Avg LOC per Function": 2.76,
        "Class Count": 175,
        "Avg LOC per Class": 22.8
      }
    },
    // more analyses...
  ],
  "next": "http://base_url/analyses/repository/:REPOSITORY_ID?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RepositoryNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "CommitsNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "NoRepositoriesForThisToken."
}

Analyses | Retrieve Analyses by Commit Hash

Request analyses by a specific hash. This endpoint supports filtering by branch, language, and root directory.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

get 
/analyses/commit/:HASH

Parameters

Field Type Description
HASH required String

Commit's unique HASH.

Query Parameter(s)

Field Type Description
branch optional String

Branch name.
language optional String

Repository's language.
root optional String

Repository's root.

Success 200

Field Type Description
user required Object

User details.
  username required String

The username of the user requesting the analysis.
  email required String

The email of the user requesting the analysis.
analyses required Object[]

Array of analysis objects, each representing a detailed analysis.
  language required String

Programming language of the code analyzed.
  root required String

Repository's root directory where the code resides.
  sha required String

Commit hash that was analyzed.
  branches required String[]

List of branches associated with the analyzed commit.
  characteristics required Object

Code characteristics such as maintainability, readability, reusability, and security scores.
  overallQualityScore required Number

Calculated overall quality score from the analysis.
  totalLocAnalyzed required Number

Total lines of code analyzed.
  totalViolationsCount required Number

Total number of violations found.
  violations required Object

Detailed counts of code violations categorized by severity (minor, major, critical).
  date required String

Date and time when the analysis was completed.
  metrics required Object

Detailed metrics of the code analyzed.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "analyses": [
    {
      "language": "Python",
      "root": "Repository root",
      "sha": "da80067a.....ac145a9a",
      "branches": ["main"],
      "characteristics": {
        "maintainabilityScore": 0.4,
        "readabilityScore": 0.55,
        "reusabilityScore": 0.65,
        "securityScore": 1
      },
      "overallQualityScore": 0.66,
      "totalLocAnalyzed": 3022,
      "totalViolationsCount": 24,
      "violations": {
        "minor": 0,
        "major": 3,
        "critical": 21
      },
      "date": "2020-05-15T09:30:00.000Z",
      "metrics": {
        "Physical Lines of Code": 3855,
        "Logical Lines of Code": 3337,
        "Dependency Vulnerabilities": 7,
        "Total Files": 201,
        "Maintainability Index": 118.516,
        "Cyclomatic Complexity": 1.03,
        "Effort (Days)": 469.69,
        "Comment Density (%)": 0.53,
        "Duplicate Code (%)": 18.55,
        "Function Count": 1579,
        "Avg LOC per Function": 2.76,
        "Class Count": 175,
        "Avg LOC per Class": 22.8
      }
    },
    // more analyses...
  ],
  "next": "http://base_url/analyses/commit/:HASH?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RepositoryNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "CommitsNotFound"
}
HTTP/1.1 404 Not Found
{
  "error": "NoRepositoriesForThisToken."
}

Teams

Teams | Retrieve Teams

Retrieves detailed information about all the teams of which the current user is a member. This includes details such as the team's name, member details including usernames and emails, and the IDs of projects associated with each team.

get 
/teams

Success 200

Field Type Description
teams required Object[]

Array of objects, each representing a team.
  _id required String

Unique identifier of the team.
  name required String

Name of the team.
  subscription required Object

Subscription details, showing active status and languages used by the team.
  members required Object[]

Array of member objects within the team, each containing the member's username and email.
  projects required String[]

Array of strings, each a unique project ID associated with the team.
  date required String

The ISO string representing the date and time when the team was created.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "teams": [
    {
      "_id": "5fa14...ddb69",
      "name": "cyclopt_team",
      "members": [
        {
          "username": "cyclopt_username",
          "email": "cyclopt_email"
        },
        // more members...
      ],
      "projects": [
        "5d948...2f243",
        "5f05e...b8459",
        // more projects...
      ],
      "date": "2020-05-15T09:30:00.000Z",
    },
    more teams...
  ]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TeamsNotFound"
}

Teams | Retrieve Team's Members

Retrieves detailed information about all teams of which the logged-in user is a member. This includes team members' roles, contact details, and activity.

get 
/teams/members

Success 200

Field Type Description
user required Object

User context for the request.
  username required String

Username of the user making the request.
  email required String

Email address of the user making the request.
members required Object[]

List of all team members.
  _id required String

Unique identifier of the team member.
  role required String

Role of the team member within the team (e.g., admin, member).
  email required String

Email address of the team member.
  username required String

Username of the team member.
  hiddenProjects required String[]

Array of project IDs that are hidden from the team member.
  lastActiveAt required String

ISO string of the last active date and time for the team member.
  createdAt required String

ISO string of the date and time when the team member was created.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "members": [
    {
      "_id": "5d948...aaf23",
      "role": "admin",
      "email": "cyclopt@cyclopt.com",
      "username": "cyclopt_user",
      "hiddenProjects": ["5d948...f2f23", "5f05e...ab845"],
      "lastActiveAt": "2020-10-15T09:30:00.000Z",
      "createdAt": "2020-05-15T09:30:00.000Z",
    }
  ]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TeamsNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "NoAccess",
}

Projects

Projects | Retrieve Projects

Retrieves information about all projects that the current user is a member of.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

get 
/projects

Query Parameter(s)

Field Type Description
includeHidden optional Boolean

Whether to include hidden projects in the response. Defaults to true.

Default value: true

Success 200

Field Type Description
username required String

Username of the user making the request.
email required String

Email of the user making the request.
projects required Object[]

Array of project objects.
  _id required String

Unique identifier of the project.
  name required String

Name of the project.
  description required String

Description of the project.
  date required String

ISO 8601 date string representing the creation time of the project.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "projects": [
    {
      "_id": "5d323...23409",
      "name": "Cyclopt Project",
      "description": "Lorem Ipsum",
      "date": "2020-05-15T09:30:00.000Z"
    }
  ],
  "next": "http://base_url/projects?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "NoProjectFound",
}

Projects | Retrieve Project's Members

Retrieves detailed information about all members assigned to a specific project identified by the project's unique ID.

get 
/projects/:PROJECT_ID/members

URL Parameters

Field Type Description
PROJECT_ID required String

The unique identifier of the project.

Success 200

Field Type Description
username required String

Username of the user making the request.
email required String

Email of the user making the request.
members required Object[]

Array of project member objects.
  _id required String

Unique identifier of the member.
  role required String

Role of the member within the project (e.g., admin, member).
  email required String

Email of the member.
  username required String

Username of the member.
  hiddenProjects required String[]

Array of hidden project IDs associated with the member.
  lastActiveAt required String

ISO 8601 date string representing the last active time of the member.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "members": [
    {
      "_id": "5d323...23499",
      "role": "admin",
      "email": "cyclopt@cyclopt.com",
      "username": "cyclopt_user",
      "hiddenProjects": ["5d323...23409", "5d323...21409"],
      "lastActiveAt": "2020-05-15T09:30:00.000Z"
    }
  ]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Retrieve Project's Repositories

Retrieves information about all repositories linked to a specific project, identified by the project's unique PROJECT_ID.

get 
/projects/:PROJECT_ID/repositories

URL Parameters

Field Type Description
PROJECT_ID required String

The unique identifier of the project.

Success 200

Field Type Description
username required String

Username of the requesting user.
email required String

Email of the requesting user.
repositories required Object[]

Array of repository objects.
  _id required String

Unique identifier of the repository.
  name required String

Name of the repository.
  owner required String

Owner of the repository.
  isPrivate required Boolean

Indicates if the repository is private.
  branches required String[]

List of all branch names in the repository.
  productionBranch required String

The main production branch of the repository.
  addedBy required Object

User who added the repository, with their username and email.
  root required String

Root directory of the repository.
  language required String

Programming language of the repository.
  date required String

Timestamp of when the repository was created.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "repositories": [
    {
      "_id": "65ef4...d2899",
      "name": "cyclopt-project",
      "owner": "cyclopt",
      "isPrivate": true,
      "branches": ["develop", "main"],
      "productionBranch": "main",
      "addedBy": {
        "email": "cyclopt2@cyclopt.com",
        "username": "cyclopt_user2"
      },
      "language": "JavaScript",
      "root": ".",
      "date": "2020-05-15T09:30:00.000Z"
    },
  ]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Retrieve Project's Analyses

Request info for all analyses that are linked to a project with a specific PROJECT_ID.

post 
/projects/:PROJECT_ID/analyses

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.

Request Body

Field Type Description
repositories required Array

The repositories to fetch analyses for.

Success 200

Field Type Description
username required String

Your username.
email required String

Your email.
_id required String

Repository's Id .
  name required String

The repository's name.
  owner required String

Owner of the repository.
  branch required Array

The selected branch of the repository.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"analyses": [{
            "owner": "repository_owner",
            "name": "repository_name",
            "branch": "master",
            "overallQuality": "B",
            "maintainability": "B⁻",
            "security": "B⁺",
            "readability": "B",
            "reusability": "B⁺"
		}],
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Retrieve Project's Tasks

Retrieves all tasks associated with a specific project, identified by the project's unique PROJECT_ID. Allows filtering to include closed tasks.

get 
/projects/:PROJECT_ID/tasks

URL Parameters

Field Type Description
PROJECT_ID required String

The unique identifier of the project.

Query Parameter(s)

Field Type Description
includeClosed optional Boolean

Optionally include tasks that are closed.

Default value: false

Success 200

Field Type Description
username required String

Username of the requesting user.
email required String

Email of the requesting user.
tasks required Object[]

Array of task objects.
  id required String

Unique identifier of the task.
  title required String

Title of the task.
  body required String

Description body of the task.
  author required String

Username of the task's author.
  closed required Boolean

Indicates if the task is closed.
  closedAt required String

Timestamp when the task was closed, null if not closed.
  assignees required Object[]

Array of assignee objects.
    username required String

Username of the assignee.
    email required String

Email of the assignee.
  dueDate required String

Due date for the task, null if not set.
  points required Object

Points details for the task.
    total required Number

Total points estimated for the task.
    done required Number

Points completed for the task.
  status required String

Current status of the task.
  priority required String

Priority level of the task.
  updatedAt required String

Timestamp of the last update to the task.
  date required String

Creation date and time of the task.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "tasks": [
    {
      "id": "6627b...91897",
      "title": "cyclopt_task",
      "body": "task_body",
      "author": "cyclopt_user2",
      "closed": false,
      "closedAt": null,
		 "sprint": null,
      "assignees": [
        {
          "username": "cyclopt_user2",
          "email": "cyclopt2@cyclopt.com"
        }
      ],
      "dueDate": null,
      "points": {
        "total": 1,
        "done": 0,
        "review": 0
      },
      "status": "Backlog",
      "priority": "none",
      "updatedAt": "2020-05-25T09:30:00.000Z",
      "date": "2020-05-15T09:30:00.000Z"
    }
  ]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Retrieve Project's Task

Retrieves detailed information about a specific task within a project. Both the project and the task are identified by their unique identifiers, PROJECT_ID and TASK_ID, respectively.

get 
/projects/:PROJECT_ID/tasks/:TASK_ID

URL Parameters

Field Type Description
PROJECT_ID required String

The unique identifier of the project.
TASK_ID required String

The unique identifier of the task.

Success 200

Field Type Description
username required String

The username of the user making the request.
email required String

The email address of the user making the request.
task required Object

The task object containing detailed information.
  id required String

The unique identifier of the task.
  title required String

The title of the task.
  body required String

The detailed description of the task.
  author required String

The username of the task's author.
  closed required Boolean

Indicates whether the task is closed.
  closedAt required String

The timestamp when the task was closed (null if not closed).
  assignees required Object[]

An array of objects containing information about the task's assignees.
    username required String

The username of the assignee.
    email required String

The email of the assignee.
  dueDate required String

The due date for the task (null if not set).
  points required Object

An object containing point details of the task.
    total required Number

The total points estimated for the task.
    done required Number

The points completed for the task.
  status required String

The current status of the task.
  priority required String

The priority level of the task (e.g., none, high, low).
  createdAt required String

The timestamp when the task was created.
  updatedAt required String

The timestamp when the task was last updated.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "task": {
    "id": "6627b...91897",
    "title": "cyclopt_task",
    "body": "",
    "author": "cyclopt_user1",
    "closed": false,
    "closedAt": null,
    "assignees": [
      {
        "username": "cyclopt_user2",
        "email": "cyclopt2@cyclopt.com"
      }
    ],
    "dueDate": null,
    "points": {
      "total": 1,
      "done": 0,
		 "review": 0
    },
    "status": "Backlog",
    "priority": "none",
	   "sprint": null,
    "createdAt": "2020-05-15T09:30:00.000Z",
    "updatedAt": "2020-05-25T09:30:00.000Z"
  }
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Create Task

Create a new task in a project with a specific PROJECT_ID.

post 
/projects/:PROJECT_ID/tasks

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.

Request Body

Field Type Description
title required String

Task's title.
body required String

Task's body.
assignees required Array

Task's assignees.
dueDate required String

Task's due date.
points required Object

Task's points.
done required Number

Task's points done.
total required Number

Task's points total.
priority required String

Task's priority [none, high, low].

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
	"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 400 Not Found
{
  "error": "TitleMissing",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Update a Project's Task

Update task with a specific TASK_ID in a project with a specific PROJECT_ID.

put 
/projects/:PROJECT_ID/tasks/:TASK_ID

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Request Body

Field Type Description
title required String

Task's title.
body required String

Task's body.
assignees required Array

Task's assignees.
dueDate required String

Task's due date.
points required Object

Task's points.
done required Number

Task's points done.
total required Number

Task's points total.
status required String

Task's status.
priority required String

Task's priority [none, high, low].

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 400 Not Found
{
  "error": "InvalidDueDate",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Create Task Comment

Add a new comment in a task with a specific TASK_ID in a project with a specific PROJECT_ID.

post 
/projects/:PROJECT_ID/tasks/:TASK_ID/comments

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Request Body

Field Type Description
body required String

Comment's body.
author required Number

Comment's author (if not the token's user).

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TaskNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Modify Task's points

Modify the points in a task with a specific TASK_ID in a project with a specific PROJECT_ID.

post 
/projects/:PROJECT_ID/tasks/:TASK_ID/points

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Request Body

Field Type Description
total required Number

Task's total points.
done required Number

Task's done points.

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TaskNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Close task

Close a task with a specific TASK_ID in a project with a specific PROJECT_ID.

patch 
/projects/:PROJECT_ID/tasks/:TASK_ID/close

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TaskNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Reopen Closed Task

Reopen a closed task with a specific TASK_ID in a project with a specific PROJECT_ID.

patch 
/projects/:PROJECT_ID/tasks/:TASK_ID/reopen

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TaskNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Projects | Delete Task

Delete a task with a specific TASK_ID in a project with a specific PROJECT_ID.

delete 
/projects/:PROJECT_ID/tasks/:TASK_ID

Parameters

Field Type Description
PROJECT_ID required Number

Project's unique ID.
TASK_ID required Number

Task's unique ID.

Success 200

Field Type Description
username required String

Your username in our database.
email required String

Your email in our database.
id required String

Task's id.

 
	HTTP 200 OK
 {
		"user": {
			"username": "cyclopt_user",
			"email": "cyclopt@cyclopt.com"
		},
		"id": "6627b...91897",
 }

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "TaskNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "ProjectNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Repositories

Repositories | Retrieve Repositories

Retrieves a list of all repositories owned by the user. This includes detailed information about each repository, such as branch information, privacy settings, and repository metadata.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

get 
/repositories

Success 200

Field Type Description
user required Object

User context for the request.
  username required String

Username of the user making the request.
  type required String

Type of user account (e.g., GitHub).
repositories required Object[]

List of repositories.
  _id required String

Unique identifier of the repository.
  name required String

Name of the repository.
  owner required String

Owner of the repository.
  isPrivate required Boolean

Indicates whether the repository is private.
  branches required String[]

List of all branch names in the repository.
  productionBranch required String

Name of the production branch.
  addedBy required Object

User who added the repository.
    email required String

Email of the user who added the repository.
    username required String

Username of the user who added the repository.
  root required String

Repository's root directory.
  language required String

Programming language of the repository.
  date required String

Date and time when the repository was created.
  isActive required Boolean

Indicates whether the repository is currently active.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "repositories": [
    {
      "_id": "65537...44978",
      "name": "cyclopt_name",
      "owner": "cyclopt_owner",
      "isPrivate": true,
      "branches": ["main", "develop"],
      "productionBranch": "main",
      "addedBy": {
        "email": "cyclopt_username",
        "username": "cyclopt_email"
      },
      "language": "C#",
      "root": ".",
      "isActive": true,
      "date": "2020-05-15T09:30:00.000Z"
    }
	  // more repositories...
  ]
  "next": "http://base_url/repositories?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RepositoriesNotFound",
}

Repositories | Retrieve Repository's Commits

Retrieves a list of commits for a specific repository identified by the unique REPOSITORY_ID.

get 
/repositories/:REPOSITORY_ID/commits/

URL Parameters

Field Type Description
REPOSITORY_ID required String

Unique identifier of the repository.

Query Parameter(s)

Field Type Description
branch optional String

Optional. Filter analyses based on the branch name.

Pagination:

Note: This endpoint supports pagination. Refer to the "General" section for details on using page and limit query params.

Success 200

Field Type Description
username required String

Username of the user making the request.
email required String

Email of the user making the request.
type required String

Type of user account (e.g., GitHub).
commits required Object[]

List of commits.
  _id required String

Unique identifier of the commit.
  branches required String[]

List of branches that include the commit.
  hash required String

Commit hash.
  authoredAt required String

ISO string of the date and time when the commit was authored.
  message required String

Commit message.

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "cyclopt_user",
    "email": "cyclopt@cyclopt.com"
  },
  "commits": [
    {
      "_id": "65537...ddf81",
      "branches": ["develop", "main"],
      "hash": "023c45..........e7d91699b14",
      "authoredAt": "2020-05-15T09:30:00.000Z",
      "message": "add a repo"
    }
  ]
  "next": "http://base_url/repositories/:REPOSITORY_ID/commits/?limit=10&page=2",
  "prev": null
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RepositoryNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "CommitsNotFound",
}
HTTP/1.1 403 Forbidden
{
  "error": "NoAccess",
}

Developers

Developers | Retrieve Developer Metrics

This endpoint returns a comprehensive snapshot of a “companion” developer’s activity, profile, and code contributions. It aggregates metrics such as lines of code, language breakdowns, repository lists, daily contributions, and monthly trend summaries.

Only authenticated users who share an active subscription order with the target developer may retrieve this data.

get 
/developers/:DEVELOPER_ID_OR_USERNAME

Parameter

Field Type Description
DEVELOPER_ID_OR_USERNAME required String

The target developer’s MongoDB ObjectId or their unique username string.

Query

Field Type Description
gitType required String

The Git provider key to query. Must be one of: github, gitlab, gitlab-draxis, gitlab-byte, gitlab-cyclopt, gitlab-liknoss, gitlab-ots, gitlab-sleed, gitlab-appart, gitlab-collectives, gitlab-ime, gitlab-ubitech, bitbucket, azure, azure-interworks, tfs-prosvasis.
range required String

JSON-encoded string with ISO date boundaries: { "start": "YYYY-MM-DDTHH:mm:ss.sssZ", "end": "YYYY-MM-DDTHH:mm:ss.sssZ" }.

Success 200

Field Type Description
user required Object

Information about the requesting user (yourself).
  username required String

Your username.
  email required String

Your email address.
stats required Object

Aggregated data for the target developer.
  developerInfo required Object

Profile and metadata for the developer.
    role required String

Assigned role label (e.g. “Frontend Engineer”).
    persona required String

Persona identifier (e.g. “The Refactorer”).
    fullName required String

Full name or display name.
    shortBio required String

Brief personal bio or tagline.
    address required String

Mailing or office address (if any).
    website required String

Personal homepage or portfolio URL.
    email required String

Public contact email.
    lastUpdate required String

ISO-8601 timestamp of the last profile change. null if never updated.

Allowed values: null

    username required Object

The developer’s unique username.
    avatar required String

URL of the avatar image.
  frameworks required Object[]

Array of framework metrics.
    name required String

Framework name (e.g. “React”).
    linesOfCode required Number

Total lines of code written in that framework.
    score required Number

Aggregate score for that framework.
    averageQuality required Number

Average code-quality metric for that framework.
    numOfRepositories required Number

Number of repositories using that framework.
  languages required Object[]

Array of language metrics.
    name required String

Language name (e.g. “JavaScript”).
    linesOfCode required Number

Total lines of code written in that language.
    score required Number

Aggregate score for that language.
    averageQuality required Number

Average code-quality metric for that language.
    numOfRepositories required Number

Number of repositories using that language.
  characteristics required Object

High-level summary of characteristic metrics. There are 8 keys: debugging, security, code, refactoring, focus, speed, efficiency, innovation.
    debugging.levelUps required String[]

List of level-up event counts (usually empty array).
    debugging.total required Number

Total debugging count.
    debugging.last7days required Number[]

Array of debugging counts for each of the last 7 days.
  repositories required Object[]

All “companion” repositories linked to this developer’s projects.
    _id required String

Repository unique identifier.
    name required String

Repository name.
    owner required String

Repository owner's username.
    isPrivate required Boolean

Whether the repository is private.
    frameworks required String[]

List of frameworks used by the repository.
    language required String

Primary programming language of the repository.
    root required String

Path to the repository root.
    createdAt required String

ISO-8601 timestamp of repository creation.
  privateRepositories required Number

Count of private repos.
  contributionsPerDay required Object[]

List of daily commit counts.
    date required String

Date in “YYYY-MM-DD” format.
    count required Number

Commit count for that date.
  trends required Object[]

Monthly breakdowns of commits, new repos, and private-repo activity.
    date required String

Month in “MMMM YYYY” format (e.g. “April 2025”).
    events required Object[]
      type required String

One of: commits, privateCommits, repo, privateRepos.
      count required Number
      title required String

Human-readable summary.
      details optional Object[]

When present, per-repository breakdown (e.g. names + commit counts).

 
HTTP/1.1 200 OK
{
  "user": {
    "username": "Papitoulini",
    "email": "panpapgeorgios@gmail.com"
  },
  "stats": {
    "developerInfo": {
      "role": "Frontend Engineer",
      "persona": "The Refactorer",
      "fullName": "George Papadopoulos",
      "shortBio": "JS enthusiast & workshop leader",
      "address": "1234 Elm Street, Athens, Greece",
      "website": "https://www.example.com",
      "email": "panpapgeorgios@gmail.com",
      "lastUpdate": "2025-04-29T11:30:00.000Z",
      "username": "Papitoulini",
      "avatar": "https://avatars.githubusercontent.com/u/113286556?...&v=4"
    },
    "frameworks": [],
    "languages": [
      [
        "JavaScript",
        {
          "linesOfCode": 23432,
          "score": 3.04,
          "averageQuality": 0.35,
          "numOfRepositories": 4
        }
      ]
    ],
    "characteristics": {
      "debugging": { "total": 200, "week": 200 },
      "security":  { "total":  27, "week":  27 },
      // … other keys …
    },
    "repositories": [
      {
        "_id": "6810b8edb6e6afc121219163",
        "name": "quality-aware-code-fixing-workshop-frontend",
        "owner": "Papitoulini",
        "isPrivate": false,
        "frameworks": [],
        "language": "JavaScript",
        "root": ".",
        "createdAt": "2025-04-29T11:33:01.154Z"
      }
      // … more repos …
    ],
    "privateRepositories": 2,
    "contributionsPerDay": [
      ["2025-04-29", 3],
      ["2025-05-02", 3],
      // … more days …
    ],
    "trends": [
      {
        "date": "May 2025",
        "events": [
          { "type": "privateCommits", "count": 3, "title": "3 commits in private repos" }
        ]
      }
      // … more months …
    ]
  }
}

400 Bad Request

Name Description
InvalidGitType required

The gitType query parameter did not match any supported provider.
InvalidRangeJSON required

The range parameter is not valid JSON.
RangeMustHaveStartAndEnd required

The range object must include both start and end properties.
RangeDatesMustBeValid required

The start or end in range is not a valid ISO date.
RangeStartMustBeBeforeEnd required

The start date must be before the end date.
RangeEndCannotBeInFuture required

The end date cannot be in the future.
RangeTooLarge required

The time span between start and end cannot exceed one year.
DeveloperNotFound required

No developer matches the given ID or username.

404 Not Found

Name Description
NoActiveOrder required

You have no active subscription order involving this developer.
CompanionProjectNotFound required

No “companion” project exists for this developer.
DeveloperStatsNotFound required

Developer statistics are unavailable or incomplete.

 
HTTP/1.1 400 Bad Request
{ "error": "InvalidGitType" }
HTTP/1.1 400 Bad Request
{ "error": "InvalidRangeJSON" }
HTTP/1.1 400 Bad Request
{ "error": "RangeStartMustBeBeforeEnd" }

Quality Gates

Quality Gates | Retrieve Status of Commit's Quality Gates

Retrieves information about the status of Quality Gates associated with the provided commit.

get 
/quality-gates/commit/:HASH

Parameters

Field Type Description
HASH required String

Commit's unique HASH.

Query Parameter(s)

Field Type Description
language optional String

Repository's language.
root optional String

Repository's root.

Success 200

Field Type Description
success required Boolean

Success of all Quality Gates linked with the provided commit, root and language.
passed required Array

List of all Quality Gates linked with the provided commit, root and language with "passed" status.
failed required Array

List of all Quality Gates linked with the provided commit, root and language with "failed" status.

 
HTTP/1.1 200 OK
{
  success: true,
  passed: ["Quality Gate 1", "Quality Gate 2"],
  failed: []
}
HTTP/1.1 200 OK
{
  success: false,
  passed: ["Quality Gate 1", "Quality Gate 2"],
  failed: ["Quality Gate 3"]
}

Error 4xx

Name Type Description
error required String

Error message describing what went wrong.

 
HTTP/1.1 404 Not Found
{
  "error": "RootOrLanguageNotValid",
}
HTTP/1.1 404 Not Found
{
  "error": "CommitNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "QualityGateCommitsNotFound",
}
HTTP/1.1 404 Not Found
{
  "error": "Still Computing...",
}