FossilRepo

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button