Skip to main content

​
Overview

Artifact Miner accepts ZIP file uploads containing one or more project directories. Once uploaded, the system extracts and catalogs the directory structure, allowing you to select specific directories for repository analysis.

​
Preparing Your ZIP File

Before uploading, organize your projects into a ZIP archive:
1

Gather your projects

Collect all project directories you want to analyze. Each project can be:
  • A Git repository (recommended for full analysis)
  • A standalone project directory
  • A collection of coursework or assignments
2

Create the ZIP archive

Compress your projects into a single ZIP file:
# Example: Create a ZIP from multiple project folders
zip -r my-projects.zip project1/ project2/ project3/
Your ZIP structure might look like:
my-projects.zip
├── web-app/
│   ├── .git/
│   ├── src/
│   └── package.json
├── data-analysis/
│   ├── .git/
│   └── notebooks/
└── mobile-app/
    ├── .git/
    └── app/
3

Verify Git repositories

Ensure your important projects contain .git directories for full repository intelligence:
# Check if a directory is a Git repository
cd project-directory
git status
Projects without Git history can still be analyzed for file types and structure, but will miss commit history, collaboration metrics, and user contribution statistics.

​
Uploading via API

Upload your ZIP file using the /zip/upload endpoint: 
curl -X POST "http://127.0.0.1:8000/zip/upload" \
  -F "[email protected]"
Response: 
{
  "zip_id": 1,
  "filename": "my-projects.zip",
  "portfolio_id": "550e8400-e29b-41d4-a716-446655440000"
}
The portfolio_id is automatically generated and links all ZIPs in the same portfolio together. Save this ID for multi-ZIP workflows.

​
Response Fields

FieldTypeDescription
zip_idintegerUnique database identifier for this upload
filenamestringOriginal filename of the uploaded ZIP
portfolio_idstringUUID linking this ZIP to a portfolio

​
Directory Selection

After upload, retrieve the directory listing to select which folders to analyze:
1

Get directory structure

Request the extracted directory tree:
curl "http://127.0.0.1:8000/zip/1/directories"
Response:
{
  "zip_id": 1,
  "filename": "my-projects.zip",
  "directories": [
    "web-app",
    "data-analysis",
    "mobile-app"
  ],
  "cleanedfilespath": [
    ".extracted/1/web-app/src/index.js",
    ".extracted/1/web-app/package.json",
    ".extracted/1/data-analysis/notebook.ipynb"
  ]
}
2

Choose directories for analysis

Select which top-level directories contain projects you want to analyze. You’ll pass these to the analyze endpoint:
{
  "directories": ["web-app", "mobile-app"]
}
If you don’t specify directories, the analysis will scan the entire extracted ZIP for Git repositories.

​
Multi-ZIP Portfolio Workflow

For large portfolios, upload multiple ZIP files incrementally to the same portfolio:
1

Upload first ZIP

Upload your first project collection:
curl -X POST "http://127.0.0.1:8000/zip/upload" \
  -F "[email protected]"
Save the returned portfolio_id.
2

Add more ZIPs to the same portfolio

Upload additional ZIPs with the same portfolio_id:
curl -X POST "http://127.0.0.1:8000/zip/upload?portfolio_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"
3

View all ZIPs in portfolio

Retrieve all uploads linked to your portfolio:
curl "http://127.0.0.1:8000/zip/portfolios/550e8400-e29b-41d4-a716-446655440000"
Response:
{
  "portfolio_id": "550e8400-e29b-41d4-a716-446655440000",
  "zips": [
    {
      "zip_id": 1,
      "filename": "semester-1-projects.zip",
      "uploaded_at": "2026-03-05T10:30:00"
    },
    {
      "zip_id": 2,
      "filename": "semester-2-projects.zip",
      "uploaded_at": "2026-03-05T10:35:00"
    }
  ]
}
Each ZIP in a portfolio is analyzed separately. When generating the final portfolio output, projects from all ZIPs are combined and deduplicated by repository name.

​
Extraction and Storage

Uploaded ZIPs are stored and extracted as follows:
  • Upload storage: ./uploads/YYYYMMDD_HHMMSS_filename.zip
  • Extraction path: ./.extracted/{zip_id}/
  • Thumbnails: ./uploads/thumbnails/ (for project images)
The extraction happens automatically when you request the directory listing or start analysis.

​
File Size and Format Requirements

  • Format: Only .zip files are accepted
  • Recommended size: Under 500 MB for optimal performance
  • Git repositories: Must include .git directory for full analysis

​
Next Steps

After uploading and selecting directories:
  1. Analyze repositories - Extract repository intelligence and user contributions
  2. Set consent preferences - Configure data handling and LLM integration
  3. Generate outputs - Create resumes and portfolio artifacts

​
API Reference

​
POST /zip/upload

Uploads a ZIP file and registers it in the database. Parameters:
  • file (form-data, required): ZIP file to upload
  • portfolio_id (query, optional): UUID to link this ZIP to an existing portfolio
Returns: ZipUploadResponse with zip_id, filename, and portfolio_id

​
GET /zip//directories

Retrieves the directory structure of an extracted ZIP. Parameters:
  • zip_id (path, required): Database ID of the uploaded ZIP
Returns: DirectoriesResponse with directory list and file paths

​
GET /zip/portfolios/

Lists all ZIPs belonging to a portfolio. Parameters:
  • portfolio_id (path, required): Portfolio UUID
Returns: PortfolioResponse with array of ZIP items

Build docs developers (and LLMs) love

Get started for freeTalk to us