Skip to main content

​
Overview

The projects API provides full CRUD operations for managing analyzed repositories, including metadata, thumbnails, roles, and evidence.

​
List Projects

Get all projects, excluding soft-deleted ones.
GET /projects
curl http://127.0.0.1:8000/projects?limit=10&offset=0
Query Parameters:
​
limit
integer
Max results to return (min: 1)
​
offset
integer
default:"0"
Number of results to skip (min: 0)
Response: 
[
  {
    "id": 1,
    "project_name": "my-app",
    "project_path": "/path/to/my-app",
    "languages": ["Python", "JavaScript"],
    "frameworks": ["FastAPI", "React"],
    "first_commit": "2023-01-15T10:00:00",
    "last_commit": "2024-03-05T14:30:00",
    "is_collaborative": true,
    "thumbnail_url": "/uploads/thumbnails/abc123.png"
  }
]
​
id
integer
Unique project identifier (RepoStat primary key)
​
project_name
string
Display name of the project
​
project_path
string
File system path to the project repository
​
languages
array
Programming languages detected in the project
​
frameworks
array
Frameworks detected in the project
​
first_commit
datetime
Timestamp of the first commit in the repository
​
last_commit
datetime
Timestamp of the most recent commit
​
is_collaborative
boolean
Whether the project has multiple contributors
​
thumbnail_url
string
URL to the project thumbnail image

​
Get Project Details

Retrieve a single project with related skills, resume items, and evidence.
GET /projects/{project_id}
curl http://127.0.0.1:8000/projects/1
Path Parameters:
​
project_id
integer
required
Project ID to retrieve
Response: 
{
  "id": 1,
  "project_name": "my-app",
  "project_path": "/path/to/my-app",
  "languages": ["Python", "JavaScript"],
  "frameworks": ["FastAPI", "React"],
  "first_commit": "2023-01-15T10:00:00",
  "last_commit": "2024-03-05T14:30:00",
  "is_collaborative": true,
  "total_commits": 342,
  "primary_language": "Python",
  "ranking_score": 85.5,
  "health_score": 92.0,
  "role": "Lead Developer",
  "thumbnail_url": "/uploads/thumbnails/abc123.png",
  "skills": [
    {
      "skill_name": "Python",
      "category": "Programming Languages",
      "proficiency": 0.9
    }
  ],
  "resume_items": [
    {
      "id": 1,
      "title": "Built REST API",
      "content": "Developed FastAPI backend...",
      "category": "Backend Development"
    }
  ],
  "evidence": [
    {
      "id": 1,
      "type": "metric",
      "content": "Improved test coverage to 95%",
      "source": "pytest",
      "date": "2024-03-01",
      "project_id": 1
    }
  ]
}
​
skills
array
Skills demonstrated in this project
​
resume_items
array
Resume items generated for this project
​
evidence
array
Evidence of success for this project

​
Set Project Thumbnail

Upload or set a thumbnail image for a project.
POST /projects/{project_id}/thumbnail
curl -X POST http://127.0.0.1:8000/projects/1/thumbnail \
  -F "[email protected]"
Path Parameters:
​
project_id
integer
required
Project ID to update
Request Body (Form Data):
​
file
file
Image file to upload (PNG or JPG, max 5 MB). Use this OR thumbnail_url, not both
​
thumbnail_url
string
External URL to use as thumbnail. Use this OR file, not both
Response: 
{
  "project_id": 1,
  "project_name": "my-app",
  "thumbnail_url": "/uploads/thumbnails/abc123def456.png"
}
Errors:
  • 422 - Must provide exactly one of file or thumbnail_url
  • 422 - Only PNG and JPG images are allowed
  • 413 - Thumbnail exceeds 5 MB size limit
  • 404 - Project not found

​
Set Project Role

Define your role in a project.
PUT /projects/{project_id}/role
curl -X PUT http://127.0.0.1:8000/projects/1/role \
  -H "Content-Type: application/json" \
  -d '{"role": "Lead Developer"}'
Path Parameters:
​
project_id
integer
required
Project ID to update
Request Body:
​
role
string
required
Your role in this project (e.g., “Lead Developer”, “Contributor”). Max 120 characters
Response: 
{
  "project_id": 1,
  "project_name": "my-app",
  "role": "Lead Developer"
}

​
Create Evidence

Add evidence of success to a project.
POST /projects/{project_id}/evidence
curl -X POST http://127.0.0.1:8000/projects/1/evidence \
  -H "Content-Type: application/json" \
  -d '{
    "type": "metric",
    "content": "Reduced API response time by 40%",
    "source": "Performance testing",
    "date": "2024-03-01"
  }'
Path Parameters:
​
project_id
integer
required
Project ID to add evidence to
Request Body:
​
type
string
required
Evidence type: metric, feedback, evaluation, award, custom, testing, documentation, code_quality, test_coverage
​
content
string
required
Description of the evidence (min 1 character)
​
source
string
Source of the evidence
​
date
date
Date of the evidence (YYYY-MM-DD)
Response: 
{
  "id": 1,
  "type": "metric",
  "content": "Reduced API response time by 40%",
  "source": "Performance testing",
  "date": "2024-03-01",
  "project_id": 1
}

​
List Evidence

Get all evidence for a project with optional type filter.
GET /projects/{project_id}/evidence?type=metric
curl http://127.0.0.1:8000/projects/1/evidence?type=metric
Query Parameters:
​
type
string
Filter by evidence type
Response: 
[
  {
    "id": 1,
    "type": "metric",
    "content": "Reduced API response time by 40%",
    "source": "Performance testing",
    "date": "2024-03-01",
    "project_id": 1
  }
]

​
Delete Evidence

Remove an evidence item from a project.
DELETE /projects/{project_id}/evidence/{evidence_id}
curl -X DELETE http://127.0.0.1:8000/projects/1/evidence/5
Response: 
{
  "success": true,
  "deleted_id": 5
}

​
Delete Project

Soft-delete a project (sets deleted_at timestamp).
DELETE /projects/{project_id}
curl -X DELETE http://127.0.0.1:8000/projects/1
Response: 
{
  "success": true,
  "message": "Project 'my-app' deleted successfully",
  "deleted_id": 1
}
Soft deletion preserves the project in the database but excludes it from queries. Related skills, resume items, and evidence are preserved.

​
Get Project Timeline

Retrieve project activity windows with optional filtering.
GET /projects/timeline?active_only=true
curl "http://127.0.0.1:8000/projects/timeline?active_only=true"
Query Parameters:
​
start_date
date
Filter projects starting after this date (YYYY-MM-DD)
​
end_date
date
Filter projects starting before this date (YYYY-MM-DD)
​
active_only
boolean
Only show projects active in the last 6 months
Response: 
[
  {
    "id": 1,
    "project_name": "my-app",
    "first_commit": "2023-01-15T10:00:00",
    "last_commit": "2024-03-05T14:30:00",
    "duration_days": 415,
    "was_active": true
  }
]

​
Get Project Ranking

Rank projects by user contribution percentage.
GET /projects/ranking
curl "http://127.0.0.1:8000/projects/ranking?projects_dir=/path/to/projects&[email protected]"
Query Parameters:
​
projects_dir
string
required
Directory containing projects to rank
​
user_email
string
required
Email to filter user contributions
Response: 
[
  {
    "name": "my-app",
    "score": 85.5,
    "total_commits": 342,
    "user_commits": 292
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us