openapi.yaml
1 openapi: 3.0.3 2 info: 3 title: Ziit API 4 description: |- 5 This is the API documentation for Ziit, a coding activity tracker. 6 The API allows you to submit coding activity heartbeats, retrieve statistics, and access user information. 7 version: 1.0.0 8 contact: 9 email: support@ziit.app 10 license: 11 name: GNU Affero General Public License v3.0 12 url: https://www.gnu.org/licenses/agpl-3.0.en.html 13 servers: 14 - url: https://ziit.app 15 description: Production Server 16 tags: 17 - name: API Routes 18 description: External API endpoints for tracking coding activity 19 - name: Public Routes 20 description: Public API endpoints that don't require authentication 21 paths: 22 /api/external/heartbeats: 23 post: 24 tags: 25 - API Routes 26 summary: Heartbeats 27 description: Submit a single coding activity heartbeat to track your work 28 operationId: submitHeartbeat 29 security: 30 - BearerAuth: [] 31 requestBody: 32 required: true 33 content: 34 application/json: 35 schema: 36 $ref: '#/components/schemas/Heartbeat' 37 responses: 38 '200': 39 description: Heartbeat successfully recorded 40 content: 41 application/json: 42 schema: 43 type: object 44 properties: 45 success: 46 type: boolean 47 id: 48 type: string 49 '400': 50 description: Validation error 51 '401': 52 description: Invalid or missing API key 53 /api/external/batch: 54 post: 55 tags: 56 - API Routes 57 summary: Batch 58 description: Submit multiple coding activity heartbeats in a single batch request (max 100) 59 operationId: submitBatchHeartbeats 60 security: 61 - BearerAuth: [] 62 requestBody: 63 required: true 64 content: 65 application/json: 66 schema: 67 type: array 68 items: 69 $ref: '#/components/schemas/Heartbeat' 70 minItems: 1 71 maxItems: 100 72 responses: 73 '200': 74 description: Batch heartbeats successfully recorded 75 content: 76 application/json: 77 schema: 78 type: object 79 properties: 80 success: 81 type: boolean 82 count: 83 type: integer 84 ids: 85 type: array 86 items: 87 type: string 88 '400': 89 description: Validation error 90 '401': 91 description: Invalid or missing API key 92 /api/external/stats: 93 get: 94 tags: 95 - API Routes 96 summary: Stats 97 description: Retrieve user coding statistics for a specific time range 98 operationId: getUserStats 99 security: 100 - BearerAuth: [] 101 parameters: 102 - in: query 103 name: timeRange 104 required: false 105 schema: 106 type: string 107 enum: 108 - today 109 - yesterday 110 - week 111 - month 112 - month_to_date 113 - last_month 114 - year_to_date 115 - last_12_months 116 - all_time 117 default: today 118 - in: query 119 name: midnightOffsetSeconds 120 required: false 121 schema: 122 type: integer 123 description: Offset in seconds from midnight for day boundaries 124 responses: 125 '200': 126 description: Statistics successfully retrieved 127 '400': 128 description: Invalid timeRange value 129 '401': 130 description: Invalid or missing API key 131 /api/external/user: 132 get: 133 tags: 134 - API Routes 135 summary: User 136 description: Retrieve user account information using API key 137 operationId: getUserInfo 138 security: 139 - BearerAuth: [] 140 responses: 141 '200': 142 description: User information successfully retrieved 143 content: 144 application/json: 145 schema: 146 $ref: '#/components/schemas/User' 147 '401': 148 description: Invalid or missing API key 149 '404': 150 description: User not found 151 /api/public/stats: 152 get: 153 tags: 154 - Public Routes 155 summary: Public Stats 156 description: Retrieve global platform statistics 157 operationId: getPublicStats 158 responses: 159 '200': 160 description: Public statistics successfully retrieved 161 content: 162 application/json: 163 schema: 164 $ref: '#/components/schemas/PublicStats' 165 '500': 166 description: Server error 167 /api/public/{badge}: 168 get: 169 tags: 170 - Public Routes 171 summary: Badge Generator 172 description: Generate SVG badges for user coding activity 173 operationId: getBadge 174 parameters: 175 - in: path 176 name: badge 177 required: true 178 schema: 179 type: string 180 description: Path segments for badge configuration 181 - in: query 182 name: style 183 required: false 184 schema: 185 type: string 186 enum: 187 - flat 188 - classic 189 default: flat 190 description: Badge style 191 - in: query 192 name: icon 193 required: false 194 schema: 195 type: string 196 description: Icon to display on badge 197 responses: 198 '200': 199 description: SVG badge successfully generated 200 content: 201 image/svg+xml: 202 schema: 203 type: string 204 '400': 205 description: Invalid parameters 206 components: 207 schemas: 208 Heartbeat: 209 type: object 210 required: 211 - timestamp 212 - project 213 - language 214 - editor 215 - os 216 - file 217 properties: 218 timestamp: 219 oneOf: 220 - type: string 221 format: date-time 222 - type: number 223 example: "2023-10-15T14:30:00Z" 224 project: 225 type: string 226 maxLength: 255 227 example: "my-awesome-project" 228 language: 229 type: string 230 maxLength: 50 231 example: "javascript" 232 editor: 233 type: string 234 maxLength: 50 235 example: "vscode" 236 os: 237 type: string 238 maxLength: 50 239 example: "macos" 240 branch: 241 type: string 242 maxLength: 255 243 example: "main" 244 file: 245 type: string 246 maxLength: 255 247 example: "App.js" 248 User: 249 type: object 250 properties: 251 id: 252 type: string 253 email: 254 type: string 255 example: "user@example.com" 256 githubId: 257 type: string 258 githubUsername: 259 type: string 260 apiKey: 261 type: string 262 format: uuid 263 keystrokeTimeout: 264 type: integer 265 PublicStats: 266 type: object 267 properties: 268 totalUsers: 269 type: integer 270 example: 1500 271 totalHeartbeats: 272 type: integer 273 example: 5000000 274 totalHours: 275 type: integer 276 example: 25000 277 topEditor: 278 type: string 279 example: "vscode" 280 topLanguage: 281 type: string 282 example: "javascript" 283 topOS: 284 type: string 285 example: "macos" 286 lastUpdated: 287 type: string 288 format: date-time 289 source: 290 type: string 291 enum: ["mixed", "live"] 292 securitySchemes: 293 BearerAuth: 294 type: http 295 scheme: bearer 296 bearerFormat: UUIDd