Skip to main content

max / synckit

vendor the openapi spec: git notes endpoints
Author: Max Johnson <me@maxj.phd> · 2026-08-09 02:42 UTC
Signed with PGP, not checked
Commit: b03c99e4cc282f148feff5a47cfab8a8d63aca8f
Parent: 33815fe
1 file changed, +479 insertions, -0 deletions
M synckit-client/tests/openapi.json +479
@@ -9,6 +9,332 @@
9 9 "version": "0.11.12"
10 10 },
11 11 "paths": {
12 + "/api/git/{owner}/{repo}/notes": {
13 + "get": {
14 + "tags": [
15 + "Git Notes"
16 + ],
17 + "summary": "`GET /api/git/{owner}/{repo}/notes`: the namespaces this repository carries.",
18 + "operationId": "list_namespaces",
19 + "parameters": [
20 + {
21 + "name": "owner",
22 + "in": "path",
23 + "description": "Repository owner's username",
24 + "required": true,
25 + "schema": {
26 + "type": "string"
27 + }
28 + },
29 + {
30 + "name": "repo",
31 + "in": "path",
32 + "description": "Repository name",
33 + "required": true,
34 + "schema": {
35 + "type": "string"
36 + }
37 + }
38 + ],
39 + "responses": {
40 + "200": {
41 + "description": "Namespaces, with a note count each",
42 + "content": {
43 + "application/json": {
44 + "schema": {
45 + "$ref": "#/components/schemas/NamespacesResponse"
46 + }
47 + }
48 + }
49 + },
50 + "404": {
51 + "description": "No such repository, or not visible to the caller"
52 + }
53 + }
54 + }
55 + },
56 + "/api/git/{owner}/{repo}/notes/search": {
57 + "get": {
58 + "tags": [
59 + "Git Notes"
60 + ],
61 + "summary": "`GET /api/git/{owner}/{repo}/notes/search`: full-text search over the index.",
62 + "description": "`search` is a static segment and an object id is 40 or 64 hex characters, so\nit can never be shadowed by, or shadow, a real target on `/notes/{target}`.",
63 + "operationId": "search_notes",
64 + "parameters": [
65 + {
66 + "name": "owner",
67 + "in": "path",
68 + "description": "Repository owner's username",
69 + "required": true,
70 + "schema": {
71 + "type": "string"
72 + }
73 + },
74 + {
75 + "name": "repo",
76 + "in": "path",
77 + "description": "Repository name",
78 + "required": true,
79 + "schema": {
80 + "type": "string"
81 + }
82 + },
83 + {
84 + "name": "q",
85 + "in": "query",
86 + "description": "Query: bare words, quoted phrases, `or`, `-excluded`",
87 + "required": true,
88 + "schema": {
89 + "type": "string"
90 + }
91 + },
92 + {
93 + "name": "namespace",
94 + "in": "query",
95 + "description": "Restrict to one namespace",
96 + "required": false,
97 + "schema": {
98 + "type": "string"
99 + }
100 + },
101 + {
102 + "name": "commits_only",
103 + "in": "query",
104 + "description": "Drop notes on blobs and trees",
105 + "required": false,
106 + "schema": {
107 + "type": "boolean"
108 + }
109 + },
110 + {
111 + "name": "limit",
112 + "in": "query",
113 + "description": "Maximum hits, default 50, capped at 200",
114 + "required": false,
115 + "schema": {
116 + "type": "integer",
117 + "format": "int64"
118 + }
119 + }
120 + ],
121 + "responses": {
122 + "200": {
123 + "description": "Matching notes, and whether the index has seen this repository",
124 + "content": {
125 + "application/json": {
126 + "schema": {
127 + "$ref": "#/components/schemas/SearchResponse"
128 + }
129 + }
130 + }
131 + },
132 + "404": {
133 + "description": "No such repository, or not visible to the caller"
134 + }
135 + }
136 + }
137 + },
138 + "/api/git/{owner}/{repo}/notes/{target}": {
139 + "get": {
140 + "tags": [
141 + "Git Notes"
142 + ],
143 + "summary": "`GET /api/git/{owner}/{repo}/notes/{target}`: one note.",
144 + "operationId": "get_note",
145 + "parameters": [
146 + {
147 + "name": "owner",
148 + "in": "path",
149 + "description": "Repository owner's username",
150 + "required": true,
151 + "schema": {
152 + "type": "string"
153 + }
154 + },
155 + {
156 + "name": "repo",
157 + "in": "path",
158 + "description": "Repository name",
159 + "required": true,
160 + "schema": {
161 + "type": "string"
162 + }
163 + },
164 + {
165 + "name": "target",
166 + "in": "path",
167 + "description": "Full object id of the annotated object",
168 + "required": true,
169 + "schema": {
170 + "type": "string"
171 + }
172 + },
173 + {
174 + "name": "namespace",
175 + "in": "query",
176 + "description": "Notes namespace, default `commits`",
177 + "required": false,
178 + "schema": {
179 + "type": "string"
180 + }
181 + },
182 + {
183 + "name": "attribution",
184 + "in": "query",
185 + "description": "Include who wrote the note; costs a bounded walk of the notes ref",
186 + "required": false,
187 + "schema": {
188 + "type": "boolean"
189 + }
190 + }
191 + ],
192 + "responses": {
193 + "200": {
194 + "description": "The note",
195 + "content": {
196 + "application/json": {
197 + "schema": {
198 + "$ref": "#/components/schemas/NoteResponse"
199 + }
200 + }
201 + }
202 + },
203 + "404": {
204 + "description": "No such repository, namespace, or note"
205 + }
206 + }
207 + },
208 + "put": {
209 + "tags": [
210 + "Git Notes"
211 + ],
212 + "summary": "`PUT /api/git/{owner}/{repo}/notes/{target}`: add or replace a note.",
213 + "operationId": "put_note",
214 + "parameters": [
215 + {
216 + "name": "owner",
217 + "in": "path",
218 + "description": "Repository owner's username",
219 + "required": true,
220 + "schema": {
221 + "type": "string"
222 + }
223 + },
224 + {
225 + "name": "repo",
226 + "in": "path",
227 + "description": "Repository name",
228 + "required": true,
229 + "schema": {
230 + "type": "string"
231 + }
232 + },
233 + {
234 + "name": "target",
235 + "in": "path",
236 + "description": "Full object id of the commit to annotate",
237 + "required": true,
238 + "schema": {
239 + "type": "string"
240 + }
241 + }
242 + ],
243 + "requestBody": {
244 + "content": {
245 + "application/json": {
246 + "schema": {
247 + "$ref": "#/components/schemas/PutNoteRequest"
248 + }
249 + }
250 + },
251 + "required": true
252 + },
253 + "responses": {
254 + "200": {
255 + "description": "What the write did",
256 + "content": {
257 + "application/json": {
258 + "schema": {
259 + "$ref": "#/components/schemas/WriteResponse"
260 + }
261 + }
262 + }
263 + },
264 + "401": {
265 + "description": "No credential; writes need a push-scoped personal access token"
266 + },
267 + "403": {
268 + "description": "A session cookie, a read-only token, or an account that cannot push here"
269 + },
270 + "404": {
271 + "description": "No such repository, or no such commit in it"
272 + },
273 + "422": {
274 + "description": "Reserved namespace, empty or oversized content, or sustained write contention"
275 + }
276 + }
277 + },
278 + "delete": {
279 + "tags": [
280 + "Git Notes"
281 + ],
282 + "summary": "`DELETE /api/git/{owner}/{repo}/notes/{target}`: remove a note.",
283 + "operationId": "delete_note",
284 + "parameters": [
285 + {
286 + "name": "owner",
287 + "in": "path",
288 + "description": "Repository owner's username",
289 + "required": true,
290 + "schema": {
291 + "type": "string"
292 + }
293 + },
294 + {
295 + "name": "repo",
296 + "in": "path",
297 + "description": "Repository name",
298 + "required": true,
299 + "schema": {
300 + "type": "string"
301 + }
302 + },
303 + {
304 + "name": "target",
305 + "in": "path",
306 + "description": "Full object id of the annotated commit",
307 + "required": true,
308 + "schema": {
309 + "type": "string"
310 + }
311 + },
312 + {
313 + "name": "namespace",
314 + "in": "query",
315 + "description": "Notes namespace, default `commits`",
316 + "required": false,
317 + "schema": {
318 + "type": "string"
319 + }
320 + }
321 + ],
322 + "responses": {
323 + "204": {
324 + "description": "The note is gone, whether or not it was there"
325 + },
326 + "401": {
327 + "description": "No credential; writes need a push-scoped personal access token"
328 + },
329 + "403": {
330 + "description": "A session cookie, a read-only token, or an account that cannot push here"
331 + },
332 + "404": {
333 + "description": "No such repository, or no such commit in it"
334 + }
335 + }
336 + }
337 + },
12 338 "/api/v1/items/{item_id}/license.txt": {
13 339 "get": {
14 340 "tags": [
@@ -1729,6 +2055,117 @@
1729 2055 }
1730 2056 }
1731 2057 },
2058 + "NamespaceEntry": {
2059 + "type": "object",
2060 + "description": "One notes namespace as the repository holds it.",
2061 + "required": [
2062 + "name",
2063 + "git_ref",
2064 + "tip",
2065 + "notes"
2066 + ],
2067 + "properties": {
2068 + "git_ref": {
2069 + "type": "string",
2070 + "description": "The ref it lives on, for a caller assembling a fetch refspec."
2071 + },
2072 + "name": {
2073 + "type": "string",
2074 + "description": "Namespace as a person says it: `commits`, `review/security`."
2075 + },
2076 + "notes": {
2077 + "type": "integer",
2078 + "format": "int64",
2079 + "description": "Notes in the namespace."
2080 + },
2081 + "tip": {
2082 + "type": "string",
2083 + "description": "Object id the ref points at."
2084 + }
2085 + }
2086 + },
2087 + "NamespacesResponse": {
2088 + "type": "object",
2089 + "required": [
2090 + "data"
2091 + ],
2092 + "properties": {
2093 + "data": {
2094 + "type": "array",
2095 + "items": {
2096 + "$ref": "#/components/schemas/NamespaceEntry"
2097 + }
2098 + }
2099 + }
2100 + },
2101 + "NoteAttribution": {
2102 + "type": "object",
2103 + "description": "Who wrote the note and when, from the notes ref's own history.",
2104 + "required": [
2105 + "commit",
2106 + "name",
2107 + "email",
2108 + "at",
2109 + "exact"
2110 + ],
2111 + "properties": {
2112 + "at": {
2113 + "type": "string",
2114 + "format": "date-time"
2115 + },
2116 + "commit": {
2117 + "type": "string",
2118 + "description": "The notes commit that set the note to what it says now."
2119 + },
2120 + "email": {
2121 + "type": "string"
2122 + },
2123 + "exact": {
2124 + "type": "boolean",
2125 + "description": "False when the bounded walk ran out before finding the change, so the\ncommit named is as far back as it looked rather than the one responsible."
2126 + },
2127 + "name": {
2128 + "type": "string"
2129 + }
2130 + }
2131 + },
2132 + "NoteResponse": {
2133 + "type": "object",
2134 + "required": [
2135 + "namespace",
2136 + "target",
2137 + "blob",
2138 + "content"
2139 + ],
2140 + "properties": {
2141 + "attribution": {
2142 + "oneOf": [
2143 + {
2144 + "type": "null"
2145 + },
2146 + {
2147 + "$ref": "#/components/schemas/NoteAttribution",
2148 + "description": "Present only when the request asked for it."
2149 + }
2150 + ]
2151 + },
2152 + "blob": {
2153 + "type": "string",
2154 + "description": "The blob holding the content."
2155 + },
2156 + "content": {
2157 + "type": "string",
2158 + "description": "Note content. Note bodies are bytes, not text; anything that is not UTF-8\nis replaced rather than rejected, since a note git accepted has to be\nreadable here."
2159 + },
2160 + "namespace": {
2161 + "type": "string"
2162 + },
2163 + "target": {
2164 + "type": "string",
2165 + "description": "The annotated object. Need not be a commit: notes on blobs and trees are\nlegal and this returns them."
2166 + }
2167 + }
2168 + },
1732 2169 "PendingKeyInfo": {
1733 2170 "type": "object",
1734 2171 "required": [
@@ -1903,6 +2340,24 @@
1903 2340 }
1904 2341 }
1905 2342 },
2343 + "PutNoteRequest": {
2344 + "type": "object",
2345 + "required": [
2346 + "content"
2347 + ],
2348 + "properties": {
2349 + "content": {
2350 + "type": "string",
2351 + "description": "The note body. Trailing whitespace is trimmed and a newline appended, the\nsame shape git's own notes carry."
2352 + },
2353 + "namespace": {
2354 + "type": [
2355 + "string",
2356 + "null"
2357 + ]
2358 + }
2359 + }
2360 + },
1906 2361 "RegisterDeviceRequest": {
1907 2362 "type": "object",
1908 2363 "required": [
@@ -2020,6 +2475,74 @@
2020 2475 }
2021 2476 }
2022 2477 },
2478 + "SearchHit": {
2479 + "type": "object",
2480 + "description": "One search hit, out of the index.",
2481 + "required": [
2482 + "namespace",
2483 + "target",
2484 + "blob",
2485 + "content",
2486 + "target_is_commit",
2487 + "summary",
2488 + "updated_at",
2489 + "updated_by"
2490 + ],
2491 + "properties": {
2492 + "blob": {
2493 + "type": "string"
2494 + },
2495 + "content": {
2496 + "type": "string"
2497 + },
2498 + "namespace": {
2499 + "type": "string"
2500 + },
2501 + "summary": {
Lines truncated