{% extends "base.html" %} {% block title %}{{ title }}{% endblock %} {% block content %}

API Reference

Complete reference for the Claude Code Tracker REST API

Interactive Docs

Base URL

http://localhost:8000

All API endpoints are relative to this base URL. The server runs on port 8000 by default.

Authentication

Currently, the API does not require authentication. All endpoints are publicly accessible when the server is running.

Projects API

GET /api/projects

Retrieve all projects with their statistics.

Response Example:
[
  {
    "id": 1,
    "name": "claude-tracker",
    "path": "/home/user/claude-tracker",
    "total_sessions": 5,
    "total_time_minutes": 240,
    "files_modified_count": 15,
    "lines_changed_count": 500,
    "last_session": "2024-01-15T10:30:00",
    "created_at": "2024-01-10T09:00:00"
  }
]
GET /api/projects/{project_id}

Get detailed information about a specific project.

Parameters:
  • project_id (integer, required): Project ID
GET /api/projects/{project_id}/stats

Get comprehensive statistics for a project including time series data.

Sessions API

POST /api/sessions/start

Start a new coding session.

Request Body:
{
  "project_path": "/path/to/project",
  "start_time": "2024-01-15T10:30:00",
  "user": "username"
}
Response:
{
  "session_id": "12345",
  "project_id": 1,
  "message": "Session started successfully"
}
POST /api/sessions/end

End an active coding session.

Request Body:
{
  "session_id": "12345",
  "end_time": "2024-01-15T12:30:00"
}
GET /api/sessions

Retrieve sessions with optional filtering.

Query Parameters:
  • project_id (integer, optional): Filter by project
  • start_date (date, optional): Sessions after this date
  • end_date (date, optional): Sessions before this date
  • limit (integer, optional): Maximum number of results

Conversations API

POST /api/conversations

Record a new conversation message.

Request Body:
{
  "session_id": "12345",
  "content": "User message or assistant response",
  "role": "user|assistant",
  "timestamp": "2024-01-15T10:35:00"
}
GET /api/conversations/search

Search conversations by content, project, or date.

Query Parameters:
  • q (string): Search query for content
  • project_id (integer): Filter by project
  • start_date (date): Messages after this date
  • end_date (date): Messages before this date
  • role (string): Filter by role (user/assistant)
  • limit (integer): Maximum results (default: 50)
GET /api/conversations

Retrieve conversations with pagination.

Activities API

POST /api/activities

Record a file modification activity.

Request Body:
{
  "session_id": "12345",
  "file_path": "/path/to/modified/file.py",
  "action": "created|modified|deleted",
  "lines_added": 10,
  "lines_removed": 5,
  "timestamp": "2024-01-15T10:40:00"
}
GET /api/activities

Retrieve file modification activities.

Query Parameters:
  • session_id (string): Filter by session
  • project_id (integer): Filter by project
  • file_path (string): Filter by file path
  • action (string): Filter by action type

Tool Calls API

POST /api/tool-calls

Record a tool call made during a Claude Code session.

Request Body:
{
  "tool_name": "Read",
  "parameters": {
    "file_path": "/path/to/file.py",
    "limit": 100
  },
  "result_status": "success",
  "execution_time_ms": 250,
  "timestamp": "2024-01-15T10:45:00"
}
GET /api/tool-calls/stats

Get tool usage statistics with optional filtering.

Query Parameters:
  • project_id (integer, optional): Filter by project
  • start_date (date, optional): Tools used after this date
  • end_date (date, optional): Tools used before this date
GET /api/tool-calls/session/{session_id}

Get all tool calls for a specific session.

Data Import API

POST /api/import/claude-data

Import data from a Claude.json file.

Request:

Multipart form data with file upload:

Content-Type: multipart/form-data

file: [claude.json file]
Response:
{
  "success": true,
  "projects_imported": 15,
  "sessions_imported": 42,
  "conversations_imported": 158,
  "activities_imported": 89,
  "errors": []
}

Error Responses

The API uses standard HTTP status codes and returns error details in JSON format.

Common Status Codes:
Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request data
404 Not Found Resource not found
500 Server Error Internal server error
Error Response Format:
{
  "error": true,
  "message": "Detailed error description",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional error context"
  }
}

Rate Limiting

Currently, no rate limiting is implemented. However, it's recommended to avoid making excessive requests to maintain optimal performance.
Quick Links
Interactive API Docs Test Projects API
API Endpoints
Code Examples
JavaScript (Fetch)
fetch('/api/projects')
  .then(r => r.json())
  .then(data => console.log(data))
Python (Requests)
import requests
r = requests.get('http://localhost:8000/api/projects')
print(r.json())
cURL
curl -X GET http://localhost:8000/api/projects
SDK & Libraries

Currently, there are no official SDKs. Use standard HTTP libraries for your preferred language.

Recommended Libraries:
  • JavaScript: fetch, axios
  • Python: requests, httpx
  • Go: net/http
  • Java: OkHttp, HttpClient
{% endblock %}