|
1
|
# API Reference |
|
2
|
|
|
3
|
FossilRepo provides a JSON API for programmatic access and an MCP server for AI tool integration. |
|
4
|
|
|
5
|
## Authentication |
|
6
|
|
|
7
|
All API endpoints accept authentication via: |
|
8
|
|
|
9
|
1. **Bearer token** (recommended for automation): |
|
10
|
``` |
|
11
|
Authorization: Bearer frp_abc123... |
|
12
|
``` |
|
13
|
Tokens can be project-scoped (API Token) or user-scoped (Personal Access Token). |
|
14
|
|
|
15
|
2. **Session cookie** (for browser-based testing): |
|
16
|
Log in via the web UI, then call API endpoints in the same browser session. |
|
17
|
|
|
18
|
## JSON API Endpoints |
|
19
|
|
|
20
|
Base URL: `/projects/<slug>/fossil/api/` |
|
21
|
|
|
22
|
### Project |
|
23
|
|
|
24
|
**GET /api/project** — Project metadata |
|
25
|
```json |
|
26
|
{"name": "FossilRepo", "slug": "fossilrepo", "description": "...", "visibility": "public", "star_count": 5} |
|
27
|
``` |
|
28
|
|
|
29
|
### Timeline |
|
30
|
|
|
31
|
**GET /api/timeline** — Recent checkins |
|
32
|
- `?page=1` — Page number |
|
33
|
- `?per_page=25` — Items per page |
|
34
|
- `?branch=trunk` — Filter by branch |
|
35
|
|
|
36
|
### Tickets |
|
37
|
|
|
38
|
**GET /api/tickets** — Ticket list |
|
39
|
- `?status=Open` — Filter by status |
|
40
|
- `?page=1&per_page=25` — Pagination |
|
41
|
|
|
42
|
**GET /api/tickets/\<uuid\>** — Single ticket with comments |
|
43
|
|
|
44
|
**GET /api/tickets/unclaimed** — Tickets available for agent claiming |
|
45
|
|
|
46
|
**POST /api/tickets/\<uuid\>/claim** — Claim ticket for exclusive work |
|
47
|
```json |
|
48
|
{"agent_id": "claude-session-abc"} |
|
49
|
``` |
|
50
|
|
|
51
|
**POST /api/tickets/\<uuid\>/release** — Release a claim |
|
52
|
|
|
53
|
**POST /api/tickets/\<uuid\>/submit** — Submit completed work |
|
54
|
```json |
|
55
|
{"summary": "Fixed by...", "workspace": "agent-fix-123"} |
|
56
|
``` |
|
57
|
|
|
58
|
### Wiki |
|
59
|
|
|
60
|
**GET /api/wiki** — Wiki page list |
|
61
|
**GET /api/wiki/\<name\>** — Page content (raw + rendered HTML) |
|
62
|
|
|
63
|
### Branches and Tags |
|
64
|
|
|
65
|
**GET /api/branches** — All branches with open/closed status |
|
66
|
**GET /api/tags** — All tags |
|
67
|
|
|
68
|
### Releases |
|
69
|
|
|
70
|
**GET /api/releases** — Release list with assets |
|
71
|
|
|
72
|
### Search |
|
73
|
|
|
74
|
**GET /api/search?q=term** — Search across checkins, tickets, wiki |
|
75
|
|
|
76
|
### CI Status |
|
77
|
|
|
78
|
**POST /api/status** — Report CI build status (Bearer token required) |
|
79
|
```json |
|
80
|
{"checkin": "abc123", "context": "ci/tests", "state": "success", "description": "All tests passed", "target_url": "https://ci.example.com/123"} |
|
81
|
``` |
|
82
|
|
|
83
|
**GET /api/status/\<checkin_uuid\>/badge.svg** — SVG status badge |
|
84
|
|
|
85
|
### Batch API |
|
86
|
|
|
87
|
**POST /api/batch** — Execute up to 25 API calls in one request |
|
88
|
```json |
|
89
|
{"requests": [ |
|
90
|
{"method": "GET", "path": "/api/timeline", "params": {"per_page": 5}}, |
|
91
|
{"method": "GET", "path": "/api/tickets", "params": {"status": "Open"}}, |
|
92
|
{"method": "GET", "path": "/api/wiki/Home"} |
|
93
|
]} |
|
94
|
``` |
|
95
|
|
|
96
|
### Agent Workspaces |
|
97
|
|
|
98
|
**GET /api/workspaces** — List active workspaces |
|
99
|
**POST /api/workspaces/create** — Create isolated workspace |
|
100
|
```json |
|
101
|
{"name": "fix-auth-bug", "agent_id": "claude-abc", "description": "Fixing auth issue"} |
|
102
|
``` |
|
103
|
**GET /api/workspaces/\<name\>** — Workspace details |
|
104
|
**POST /api/workspaces/\<name\>/commit** — Commit changes |
|
105
|
**POST /api/workspaces/\<name\>/merge** — Merge back to trunk |
|
106
|
**DELETE /api/workspaces/\<name\>/abandon** — Abandon workspace |
|
107
|
|
|
108
|
### Code Reviews |
|
109
|
|
|
110
|
**GET /api/reviews** — List reviews (filterable by status) |
|
111
|
**POST /api/reviews/create** — Submit code for review |
|
112
|
```json |
|
113
|
{"title": "Fix null pointer", "description": "...", "diff": "--- a/...", "files_changed": ["src/auth.py"]} |
|
114
|
``` |
|
115
|
**GET /api/reviews/\<id\>** — Review with comments |
|
116
|
**POST /api/reviews/\<id\>/comment** — Add review comment |
|
117
|
**POST /api/reviews/\<id\>/approve** — Approve |
|
118
|
**POST /api/reviews/\<id\>/request-changes** — Request changes |
|
119
|
**POST /api/reviews/\<id\>/merge** — Merge approved review |
|
120
|
|
|
121
|
### Server-Sent Events |
|
122
|
|
|
123
|
**GET /api/events** — Real-time event stream |
|
124
|
``` |
|
125
|
event: checkin |
|
126
|
data: {"uuid": "abc123", "user": "dev", "comment": "Fix bug"} |
|
127
|
|
|
128
|
event: claim |
|
129
|
data: {"ticket": "def456", "agent": "claude-abc", "status": "claimed"} |
|
130
|
|
|
131
|
event: workspace |
|
132
|
data: {"name": "fix-auth", "branch": "workspace/fix-auth", "status": "merged"} |
|
133
|
``` |
|
134
|
|
|
135
|
## MCP Server |
|
136
|
|
|
137
|
The MCP (Model Context Protocol) server gives AI tools native access to FossilRepo. |
|
138
|
|
|
139
|
### Setup |
|
140
|
|
|
141
|
```bash |
|
142
|
pip install fossilrepo |
|
143
|
fossilrepo-mcp |
|
144
|
``` |
|
145
|
|
|
146
|
### Claude Code Configuration |
|
147
|
|
|
148
|
```json |
|
149
|
{ |
|
150
|
"mcpServers": { |
|
151
|
"fossilrepo": { |
|
152
|
"command": "fossilrepo-mcp" |
|
153
|
} |
|
154
|
} |
|
155
|
} |
|
156
|
``` |
|
157
|
|
|
158
|
### Available Tools |
|
159
|
|
|
160
|
| Tool | Description | |
|
161
|
|------|-------------| |
|
162
|
| list_projects | List all projects | |
|
163
|
| get_project | Project details with repo stats | |
|
164
|
| browse_code | List files in a directory | |
|
165
|
| read_file | Read file content | |
|
166
|
| get_timeline | Recent checkins (optional branch filter) | |
|
167
|
| get_checkin | Checkin detail with file changes | |
|
168
|
| search_code | Search across checkins, tickets, wiki | |
|
169
|
| list_tickets | List tickets (optional status filter) | |
|
170
|
| get_ticket | Ticket detail with comments | |
|
171
|
| create_ticket | Create a new ticket | |
|
172
|
| update_ticket | Update ticket status, add comment | |
|
173
|
| list_wiki_pages | List all wiki pages | |
|
174
|
| get_wiki_page | Read wiki page content | |
|
175
|
| list_branches | List all branches | |
|
176
|
| get_file_blame | Blame annotations for a file | |
|
177
|
| get_file_history | Commit history for a file | |
|
178
|
| sql_query | Run read-only SQL against Fossil SQLite | |
|
179
|
|
|
180
|
All tools accept a `slug` parameter to identify the project. |
|
181
|
|