immersivecommons 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/README.md +67 -0
- data/lib/immersivecommons/client.rb +252 -0
- data/lib/immersivecommons/generated.rb +291 -0
- data/lib/immersivecommons/openapi.json +2951 -0
- data/lib/immersivecommons/version.rb +5 -0
- data/lib/immersivecommons.rb +11 -0
- metadata +58 -0
|
@@ -0,0 +1,2951 @@
|
|
|
1
|
+
{
|
|
2
|
+
"openapi": "3.1.1",
|
|
3
|
+
"info": {
|
|
4
|
+
"title": "Immersive Commons — Agent REST API",
|
|
5
|
+
"version": "2026-07-16",
|
|
6
|
+
"summary": "The REST surface an AI agent uses to act at Immersive Commons.",
|
|
7
|
+
"description": "Machine-readable description of the Immersive Commons REST API for AI agents.\n\n**Authentication.** Most operations take a Bearer agent token (`Authorization: Bearer agt_...`). Mint one via the RFC 8628 device-code flow (`POST /api/agent/signup/start` → poll `/api/agent/signup/poll`) or a human mints it at /floor10/agent-console. Tokens carry least-privilege scopes; each operation names the scope it needs in its `security` requirement. Public reads allow anonymous access (empty security requirement). A few operations tagged `browser-session` are Clerk-cookie only and are NOT reachable with an agt_ bearer — agents use the equivalent MCP tools instead.\n\n**Error model.** Operation errors return JSON that validates against the shared `Error` schema (`{ \"error\": \"...\" }`, optionally `ok:false`/`error_kind`/`rate`/`retry_after_seconds`). Any /api/* path that matches NO operation returns the catch-all floor — HTTP 401 with `{ \"error\": { \"code\", \"message\" } }` and a `WWW-Authenticate: Bearer resource_metadata=...` header pointing at /.well-known/oauth-protected-resource.\n\n**Idempotency.** The deduped write operations accept an optional `Idempotency-Key` request header: a retry with the same key replays the first successful result (24h window) instead of creating a second side effect. This layers on top of each endpoint's own semantic dedupe (e.g. RSVP's 7-day window).\n\n**Versioning & deprecation policy.** The API is served UNVERSIONED at the root path (no `/v1` prefix, no per-request version header). The dated `info.version` (CalVer) is the change marker to pin against. No operation is deprecated today; when one is scheduled for removal it will be marked `deprecated: true` here and carry RFC 8594 `Deprecation` + `Sunset` response headers, announced at least 90 days ahead via /developers and llms.txt. Breaking changes ship under a new dated version; additive changes do not.\n\n**Rate limits.** Agent tokens are limited per-token per endpoint family (e.g. 3 highlight submissions/day, 60 research queries/hour). 429 responses carry a `Retry-After` header.",
|
|
8
|
+
"contact": {
|
|
9
|
+
"name": "Immersive Commons",
|
|
10
|
+
"email": "admin@immersivecommons.com",
|
|
11
|
+
"url": "https://www.immersivecommons.com/developers"
|
|
12
|
+
},
|
|
13
|
+
"license": {
|
|
14
|
+
"name": "Proprietary",
|
|
15
|
+
"url": "https://www.immersivecommons.com/privacy"
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"servers": [
|
|
19
|
+
{
|
|
20
|
+
"url": "https://www.immersivecommons.com",
|
|
21
|
+
"description": "Production"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"url": "https://www.immersivecommons.com",
|
|
25
|
+
"description": "Sandbox (test mode) — same base URL; mint a sandbox token via `sandbox:true` on /api/agent/signup/start. Writes return simulated receipts, reads serve real data.",
|
|
26
|
+
"x-sandbox": "token-flag"
|
|
27
|
+
}
|
|
28
|
+
],
|
|
29
|
+
"x-payment-info": {
|
|
30
|
+
"protocol": "x402",
|
|
31
|
+
"discovery": "https://www.immersivecommons.com/discovery/resources",
|
|
32
|
+
"donor_wall": "https://www.immersivecommons.com/api/floor10/donations",
|
|
33
|
+
"note": "Payable resources are advertised at /discovery/resources; a bare request to a payable resource returns HTTP 402 with the PAYMENT-REQUIRED challenge."
|
|
34
|
+
},
|
|
35
|
+
"x-api-lifecycle": {
|
|
36
|
+
"versioning": "unversioned-root (info.version is a dated CalVer change marker)",
|
|
37
|
+
"deprecation": "deprecated operations are flagged here + carry RFC 8594 Deprecation/Sunset headers, >=90 days notice"
|
|
38
|
+
},
|
|
39
|
+
"x-sandbox": {
|
|
40
|
+
"summary": "A sandbox token (mint by adding \"sandbox\": true to POST /api/agent/signup/start) is a real token with real scopes whose WRITE operations return a simulated receipt instead of mutating; reads serve real data. Same base URL + bearer auth. Immutable after mint.",
|
|
41
|
+
"obtain": {
|
|
42
|
+
"endpoint": "POST /api/agent/signup/start",
|
|
43
|
+
"body": {
|
|
44
|
+
"sandbox": true
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
"write_response_shape": {
|
|
48
|
+
"ok": true,
|
|
49
|
+
"sandbox": true,
|
|
50
|
+
"simulated": true,
|
|
51
|
+
"would_have": {
|
|
52
|
+
"action": "string",
|
|
53
|
+
"scope": "string",
|
|
54
|
+
"args": "object"
|
|
55
|
+
},
|
|
56
|
+
"note": "string — scope was checked; deeper business rules (tier/role/ownership/signature) are NOT evaluated in sandbox, and no production state changed. A green receipt means well-formed + scoped, NOT guaranteed to pass in production."
|
|
57
|
+
},
|
|
58
|
+
"real_exceptions": [
|
|
59
|
+
"POST /api/agent/feedback (bug-report channel must be heard)",
|
|
60
|
+
"POST /api/agent/token/revoke (token lifecycle; genuinely revokes)"
|
|
61
|
+
],
|
|
62
|
+
"not_sandbox_eligible": [
|
|
63
|
+
"ic_donate (x402 payment rail — never faked; not a REST operation in this spec)",
|
|
64
|
+
"floor-admin toggles + tools with no concrete scope to check — denied fail-closed, never silently simulated"
|
|
65
|
+
]
|
|
66
|
+
},
|
|
67
|
+
"tags": [
|
|
68
|
+
{
|
|
69
|
+
"name": "events",
|
|
70
|
+
"description": "Discover and RSVP to events; propose member events."
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"name": "batch",
|
|
74
|
+
"description": "Fan out several public GET reads in one request."
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"name": "directory",
|
|
78
|
+
"description": "Search the member directory."
|
|
79
|
+
},
|
|
80
|
+
{
|
|
81
|
+
"name": "resources",
|
|
82
|
+
"description": "List and book rooms / printers."
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
"name": "account",
|
|
86
|
+
"description": "The caller's own activity log."
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
"name": "leaderboard",
|
|
90
|
+
"description": "The public commit leaderboard."
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
"name": "research",
|
|
94
|
+
"description": "Query the research RAG corpus."
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
"name": "highlights",
|
|
98
|
+
"description": "Submit event highlights for moderation."
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
"name": "feedback",
|
|
102
|
+
"description": "File feedback / breakage reports."
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
"name": "auth",
|
|
106
|
+
"description": "Token mint (device code), self-revoke, setup checks."
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
"name": "payments",
|
|
110
|
+
"description": "x402 machine payments (donor wall)."
|
|
111
|
+
},
|
|
112
|
+
{
|
|
113
|
+
"name": "membership",
|
|
114
|
+
"description": "Membership tier (browser-session)."
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"name": "browser-session",
|
|
118
|
+
"description": "Clerk-cookie only — NOT reachable with an agt_ bearer."
|
|
119
|
+
}
|
|
120
|
+
],
|
|
121
|
+
"security": [
|
|
122
|
+
{}
|
|
123
|
+
],
|
|
124
|
+
"paths": {
|
|
125
|
+
"/api/events/upcoming": {
|
|
126
|
+
"get": {
|
|
127
|
+
"operationId": "listUpcomingEvents",
|
|
128
|
+
"tags": [
|
|
129
|
+
"events"
|
|
130
|
+
],
|
|
131
|
+
"summary": "List upcoming Immersive Commons events",
|
|
132
|
+
"description": "Public read of the upcoming-events KV cache. Anonymous, or authenticated with a Clerk session or an agt_ token carrying `events:read_upcoming`. Returns the events plus an `age_min` staleness gauge. Use `limit` to cap the page size (there is no cursor — the full upcoming window is small).",
|
|
133
|
+
"security": [
|
|
134
|
+
{},
|
|
135
|
+
{
|
|
136
|
+
"agentBearer": [
|
|
137
|
+
"events:read_upcoming"
|
|
138
|
+
]
|
|
139
|
+
}
|
|
140
|
+
],
|
|
141
|
+
"parameters": [
|
|
142
|
+
{
|
|
143
|
+
"name": "limit",
|
|
144
|
+
"in": "query",
|
|
145
|
+
"required": false,
|
|
146
|
+
"schema": {
|
|
147
|
+
"type": "integer",
|
|
148
|
+
"minimum": 1
|
|
149
|
+
},
|
|
150
|
+
"description": "Max events to return."
|
|
151
|
+
}
|
|
152
|
+
],
|
|
153
|
+
"responses": {
|
|
154
|
+
"200": {
|
|
155
|
+
"description": "Upcoming events.",
|
|
156
|
+
"content": {
|
|
157
|
+
"application/json": {
|
|
158
|
+
"schema": {
|
|
159
|
+
"$ref": "#/components/schemas/UpcomingEventsResponse"
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
"500": {
|
|
165
|
+
"description": "Cache read failed.",
|
|
166
|
+
"content": {
|
|
167
|
+
"application/json": {
|
|
168
|
+
"schema": {
|
|
169
|
+
"$ref": "#/components/schemas/Error"
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
},
|
|
175
|
+
"x-ic-route": {
|
|
176
|
+
"file": "app/api/events/upcoming/route.ts",
|
|
177
|
+
"method": "GET"
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
"/api/events/get": {
|
|
182
|
+
"get": {
|
|
183
|
+
"operationId": "getEventByLumaUrl",
|
|
184
|
+
"tags": [
|
|
185
|
+
"events"
|
|
186
|
+
],
|
|
187
|
+
"summary": "Look up a single event by its Luma URL",
|
|
188
|
+
"description": "Public. Resolves one event from the upcoming cache by its canonical Luma URL.",
|
|
189
|
+
"security": [
|
|
190
|
+
{}
|
|
191
|
+
],
|
|
192
|
+
"parameters": [
|
|
193
|
+
{
|
|
194
|
+
"name": "luma",
|
|
195
|
+
"in": "query",
|
|
196
|
+
"required": true,
|
|
197
|
+
"schema": {
|
|
198
|
+
"type": "string"
|
|
199
|
+
},
|
|
200
|
+
"description": "Canonical Luma event URL (https://luma.com/<slug> or https://lu.ma/<slug>)."
|
|
201
|
+
}
|
|
202
|
+
],
|
|
203
|
+
"responses": {
|
|
204
|
+
"200": {
|
|
205
|
+
"description": "The matching event.",
|
|
206
|
+
"content": {
|
|
207
|
+
"application/json": {
|
|
208
|
+
"schema": {
|
|
209
|
+
"$ref": "#/components/schemas/EventGetResponse"
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
},
|
|
214
|
+
"400": {
|
|
215
|
+
"description": "Missing or non-canonical `luma` URL.",
|
|
216
|
+
"content": {
|
|
217
|
+
"application/json": {
|
|
218
|
+
"schema": {
|
|
219
|
+
"$ref": "#/components/schemas/Error"
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
},
|
|
224
|
+
"404": {
|
|
225
|
+
"description": "No matching event in the upcoming cache.",
|
|
226
|
+
"content": {
|
|
227
|
+
"application/json": {
|
|
228
|
+
"schema": {
|
|
229
|
+
"$ref": "#/components/schemas/Error"
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
},
|
|
235
|
+
"x-ic-route": {
|
|
236
|
+
"file": "app/api/events/get/route.ts",
|
|
237
|
+
"method": "GET"
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
},
|
|
241
|
+
"/api/batch": {
|
|
242
|
+
"post": {
|
|
243
|
+
"operationId": "batchPublicReads",
|
|
244
|
+
"x-sandbox": "real",
|
|
245
|
+
"tags": [
|
|
246
|
+
"batch"
|
|
247
|
+
],
|
|
248
|
+
"summary": "Run up to 20 public GET reads in one request",
|
|
249
|
+
"description": "Public, no auth. Submit a bounded list (1..20) of GET sub-requests to the allowlisted PUBLIC read endpoints (`/api/events/upcoming`, `/api/events/get`, `/api/floor10/donations`) and get their results back in order. Each sub-request is dispatched to the SAME handler that serves it directly, so a batched result is identical to calling that endpoint alone. Writes and auth-gated reads are deliberately NOT batchable (they keep their own idempotency + per-token rate accounting). Partial-failure semantics: a rejected sub-request (non-GET, non-allowlisted path, handler error) carries a 4xx/5xx status inside its own result while the batch envelope stays 200; only a malformed batch envelope is a 400 on the whole call.",
|
|
250
|
+
"security": [
|
|
251
|
+
{}
|
|
252
|
+
],
|
|
253
|
+
"requestBody": {
|
|
254
|
+
"required": true,
|
|
255
|
+
"content": {
|
|
256
|
+
"application/json": {
|
|
257
|
+
"schema": {
|
|
258
|
+
"$ref": "#/components/schemas/BatchRequest"
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
},
|
|
263
|
+
"responses": {
|
|
264
|
+
"200": {
|
|
265
|
+
"description": "Per-sub-request results, in the same order as `requests`.",
|
|
266
|
+
"content": {
|
|
267
|
+
"application/json": {
|
|
268
|
+
"schema": {
|
|
269
|
+
"$ref": "#/components/schemas/BatchResponse"
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
},
|
|
274
|
+
"400": {
|
|
275
|
+
"description": "Malformed batch envelope: bad JSON, wrong shape, empty, or more than 20 sub-requests.",
|
|
276
|
+
"content": {
|
|
277
|
+
"application/json": {
|
|
278
|
+
"schema": {
|
|
279
|
+
"$ref": "#/components/schemas/Error"
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
},
|
|
284
|
+
"413": {
|
|
285
|
+
"description": "Batch body exceeds 16KB.",
|
|
286
|
+
"content": {
|
|
287
|
+
"application/json": {
|
|
288
|
+
"schema": {
|
|
289
|
+
"$ref": "#/components/schemas/Error"
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
},
|
|
295
|
+
"x-ic-route": {
|
|
296
|
+
"file": "app/api/batch/route.ts",
|
|
297
|
+
"method": "POST"
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
},
|
|
301
|
+
"/api/events/next": {
|
|
302
|
+
"get": {
|
|
303
|
+
"operationId": "tailAgentEvents",
|
|
304
|
+
"tags": [
|
|
305
|
+
"events",
|
|
306
|
+
"browser-session"
|
|
307
|
+
],
|
|
308
|
+
"summary": "Cursor-tail the caller's agentic event log",
|
|
309
|
+
"description": "Clerk-session only (NOT reachable with an agt_ bearer). Cursor-based tail read of the per-user agentic event log. Pass the last-seen `since` id to page forward; the response carries `cursor` + `has_more` for the next page. Headless agents use the MCP verb `ic_events_next` (bearer-auth) instead.",
|
|
310
|
+
"security": [
|
|
311
|
+
{
|
|
312
|
+
"clerkSession": []
|
|
313
|
+
}
|
|
314
|
+
],
|
|
315
|
+
"parameters": [
|
|
316
|
+
{
|
|
317
|
+
"name": "since",
|
|
318
|
+
"in": "query",
|
|
319
|
+
"required": false,
|
|
320
|
+
"schema": {
|
|
321
|
+
"type": "integer",
|
|
322
|
+
"minimum": 0
|
|
323
|
+
},
|
|
324
|
+
"description": "Numeric cursor = last-seen event id. Omit for the backlog head."
|
|
325
|
+
},
|
|
326
|
+
{
|
|
327
|
+
"name": "types",
|
|
328
|
+
"in": "query",
|
|
329
|
+
"required": false,
|
|
330
|
+
"schema": {
|
|
331
|
+
"type": "string"
|
|
332
|
+
},
|
|
333
|
+
"description": "Comma-separated AgentEventType filter."
|
|
334
|
+
},
|
|
335
|
+
{
|
|
336
|
+
"name": "limit",
|
|
337
|
+
"in": "query",
|
|
338
|
+
"required": false,
|
|
339
|
+
"schema": {
|
|
340
|
+
"type": "integer",
|
|
341
|
+
"minimum": 1,
|
|
342
|
+
"maximum": 500,
|
|
343
|
+
"default": 50
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
],
|
|
347
|
+
"responses": {
|
|
348
|
+
"200": {
|
|
349
|
+
"description": "A page of agent events with a forward cursor.",
|
|
350
|
+
"content": {
|
|
351
|
+
"application/json": {
|
|
352
|
+
"schema": {
|
|
353
|
+
"$ref": "#/components/schemas/AgentEventsNextResponse"
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
},
|
|
358
|
+
"401": {
|
|
359
|
+
"description": "Not signed in.",
|
|
360
|
+
"content": {
|
|
361
|
+
"application/json": {
|
|
362
|
+
"schema": {
|
|
363
|
+
"$ref": "#/components/schemas/Error"
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
},
|
|
368
|
+
"500": {
|
|
369
|
+
"description": "Event log read failed.",
|
|
370
|
+
"content": {
|
|
371
|
+
"application/json": {
|
|
372
|
+
"schema": {
|
|
373
|
+
"$ref": "#/components/schemas/Error"
|
|
374
|
+
}
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
},
|
|
379
|
+
"x-ic-route": {
|
|
380
|
+
"file": "app/api/events/next/route.ts",
|
|
381
|
+
"method": "GET"
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
},
|
|
385
|
+
"/api/events/rsvp": {
|
|
386
|
+
"post": {
|
|
387
|
+
"operationId": "rsvpToEvent",
|
|
388
|
+
"x-sandbox": "simulated",
|
|
389
|
+
"tags": [
|
|
390
|
+
"events"
|
|
391
|
+
],
|
|
392
|
+
"summary": "Queue an RSVP to a Luma event",
|
|
393
|
+
"description": "Clerk session or agt_ token with `events:rsvp`. Queues an RSVP envelope for life-side processing (returns `queued`, not a confirmed Luma seat). IDEMPOTENT: a repeat within 7 days is recognized (`was_dup: true`) and no second envelope is written; an `Idempotency-Key` additionally replays the first result. Agent callers MUST supply `email` (no session fallback).",
|
|
394
|
+
"security": [
|
|
395
|
+
{
|
|
396
|
+
"agentBearer": [
|
|
397
|
+
"events:rsvp"
|
|
398
|
+
]
|
|
399
|
+
}
|
|
400
|
+
],
|
|
401
|
+
"parameters": [
|
|
402
|
+
{
|
|
403
|
+
"name": "Idempotency-Key",
|
|
404
|
+
"in": "header",
|
|
405
|
+
"required": false,
|
|
406
|
+
"schema": {
|
|
407
|
+
"type": "string",
|
|
408
|
+
"maxLength": 255
|
|
409
|
+
},
|
|
410
|
+
"description": "Optional. A retry carrying the same key replays the first successful result verbatim instead of creating a second side effect (honored by lib/idempotency.ts, 24h window). Complementary to each endpoint's own semantic dedupe. Absent = no replay."
|
|
411
|
+
}
|
|
412
|
+
],
|
|
413
|
+
"requestBody": {
|
|
414
|
+
"required": true,
|
|
415
|
+
"content": {
|
|
416
|
+
"application/json": {
|
|
417
|
+
"schema": {
|
|
418
|
+
"$ref": "#/components/schemas/RsvpRequest"
|
|
419
|
+
}
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
},
|
|
423
|
+
"responses": {
|
|
424
|
+
"200": {
|
|
425
|
+
"description": "RSVP queued (or recognized as a duplicate).",
|
|
426
|
+
"content": {
|
|
427
|
+
"application/json": {
|
|
428
|
+
"schema": {
|
|
429
|
+
"$ref": "#/components/schemas/QueueResponse"
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
},
|
|
434
|
+
"400": {
|
|
435
|
+
"description": "Bad event_url, missing email on the agent path, or validation error.",
|
|
436
|
+
"content": {
|
|
437
|
+
"application/json": {
|
|
438
|
+
"schema": {
|
|
439
|
+
"$ref": "#/components/schemas/Error"
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
},
|
|
444
|
+
"401": {
|
|
445
|
+
"description": "Missing/invalid token or session.",
|
|
446
|
+
"content": {
|
|
447
|
+
"application/json": {
|
|
448
|
+
"schema": {
|
|
449
|
+
"$ref": "#/components/schemas/Error"
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
},
|
|
454
|
+
"403": {
|
|
455
|
+
"description": "Token scope or live tier does not authorize events:rsvp.",
|
|
456
|
+
"content": {
|
|
457
|
+
"application/json": {
|
|
458
|
+
"schema": {
|
|
459
|
+
"$ref": "#/components/schemas/Error"
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
},
|
|
464
|
+
"413": {
|
|
465
|
+
"description": "Body exceeds 8KB.",
|
|
466
|
+
"content": {
|
|
467
|
+
"application/json": {
|
|
468
|
+
"schema": {
|
|
469
|
+
"$ref": "#/components/schemas/Error"
|
|
470
|
+
}
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
},
|
|
474
|
+
"429": {
|
|
475
|
+
"description": "Per-token rate limit exceeded.",
|
|
476
|
+
"content": {
|
|
477
|
+
"application/json": {
|
|
478
|
+
"schema": {
|
|
479
|
+
"$ref": "#/components/schemas/Error"
|
|
480
|
+
}
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
},
|
|
484
|
+
"500": {
|
|
485
|
+
"description": "KV write failed.",
|
|
486
|
+
"content": {
|
|
487
|
+
"application/json": {
|
|
488
|
+
"schema": {
|
|
489
|
+
"$ref": "#/components/schemas/Error"
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
},
|
|
495
|
+
"x-ic-route": {
|
|
496
|
+
"file": "app/api/events/rsvp/route.ts",
|
|
497
|
+
"method": "POST"
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
},
|
|
501
|
+
"/api/events/request": {
|
|
502
|
+
"post": {
|
|
503
|
+
"operationId": "requestEvent",
|
|
504
|
+
"x-sandbox": "simulated",
|
|
505
|
+
"tags": [
|
|
506
|
+
"events"
|
|
507
|
+
],
|
|
508
|
+
"summary": "Propose a member event (operator-approved)",
|
|
509
|
+
"description": "Clerk session or agt_ token with `events:request` (ic-member+). Enqueues a Luma-shaped 'save the date' into the pending queue for operator approval — it NEVER auto-creates a public event. Supports an `Idempotency-Key`.",
|
|
510
|
+
"security": [
|
|
511
|
+
{
|
|
512
|
+
"agentBearer": [
|
|
513
|
+
"events:request"
|
|
514
|
+
]
|
|
515
|
+
}
|
|
516
|
+
],
|
|
517
|
+
"parameters": [
|
|
518
|
+
{
|
|
519
|
+
"name": "Idempotency-Key",
|
|
520
|
+
"in": "header",
|
|
521
|
+
"required": false,
|
|
522
|
+
"schema": {
|
|
523
|
+
"type": "string",
|
|
524
|
+
"maxLength": 255
|
|
525
|
+
},
|
|
526
|
+
"description": "Optional. A retry carrying the same key replays the first successful result verbatim instead of creating a second side effect (honored by lib/idempotency.ts, 24h window). Complementary to each endpoint's own semantic dedupe. Absent = no replay."
|
|
527
|
+
}
|
|
528
|
+
],
|
|
529
|
+
"requestBody": {
|
|
530
|
+
"required": true,
|
|
531
|
+
"content": {
|
|
532
|
+
"application/json": {
|
|
533
|
+
"schema": {
|
|
534
|
+
"$ref": "#/components/schemas/EventRequestRequest"
|
|
535
|
+
}
|
|
536
|
+
}
|
|
537
|
+
}
|
|
538
|
+
},
|
|
539
|
+
"responses": {
|
|
540
|
+
"200": {
|
|
541
|
+
"description": "Request enqueued as pending.",
|
|
542
|
+
"content": {
|
|
543
|
+
"application/json": {
|
|
544
|
+
"schema": {
|
|
545
|
+
"$ref": "#/components/schemas/EventRequestResponse"
|
|
546
|
+
}
|
|
547
|
+
}
|
|
548
|
+
}
|
|
549
|
+
},
|
|
550
|
+
"400": {
|
|
551
|
+
"description": "Invalid JSON or field.",
|
|
552
|
+
"content": {
|
|
553
|
+
"application/json": {
|
|
554
|
+
"schema": {
|
|
555
|
+
"$ref": "#/components/schemas/Error"
|
|
556
|
+
}
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
},
|
|
560
|
+
"401": {
|
|
561
|
+
"description": "No auth.",
|
|
562
|
+
"content": {
|
|
563
|
+
"application/json": {
|
|
564
|
+
"schema": {
|
|
565
|
+
"$ref": "#/components/schemas/Error"
|
|
566
|
+
}
|
|
567
|
+
}
|
|
568
|
+
}
|
|
569
|
+
},
|
|
570
|
+
"403": {
|
|
571
|
+
"description": "Tier/scope does not authorize events:request.",
|
|
572
|
+
"content": {
|
|
573
|
+
"application/json": {
|
|
574
|
+
"schema": {
|
|
575
|
+
"$ref": "#/components/schemas/Error"
|
|
576
|
+
}
|
|
577
|
+
}
|
|
578
|
+
}
|
|
579
|
+
},
|
|
580
|
+
"429": {
|
|
581
|
+
"description": "Per-member daily cap reached.",
|
|
582
|
+
"content": {
|
|
583
|
+
"application/json": {
|
|
584
|
+
"schema": {
|
|
585
|
+
"$ref": "#/components/schemas/Error"
|
|
586
|
+
}
|
|
587
|
+
}
|
|
588
|
+
}
|
|
589
|
+
},
|
|
590
|
+
"500": {
|
|
591
|
+
"description": "Queue write failed.",
|
|
592
|
+
"content": {
|
|
593
|
+
"application/json": {
|
|
594
|
+
"schema": {
|
|
595
|
+
"$ref": "#/components/schemas/Error"
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
}
|
|
599
|
+
},
|
|
600
|
+
"503": {
|
|
601
|
+
"description": "Rate limiter unavailable.",
|
|
602
|
+
"content": {
|
|
603
|
+
"application/json": {
|
|
604
|
+
"schema": {
|
|
605
|
+
"$ref": "#/components/schemas/Error"
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
},
|
|
611
|
+
"x-ic-route": {
|
|
612
|
+
"file": "app/api/events/request/route.ts",
|
|
613
|
+
"method": "POST"
|
|
614
|
+
}
|
|
615
|
+
}
|
|
616
|
+
},
|
|
617
|
+
"/api/directory/search": {
|
|
618
|
+
"get": {
|
|
619
|
+
"operationId": "searchDirectory",
|
|
620
|
+
"tags": [
|
|
621
|
+
"directory"
|
|
622
|
+
],
|
|
623
|
+
"summary": "Search the member directory",
|
|
624
|
+
"description": "Clerk session or agt_ token with `directory:search`. Privacy-graded search over the member roster; the fields returned depend on the caller's tier.",
|
|
625
|
+
"security": [
|
|
626
|
+
{
|
|
627
|
+
"agentBearer": [
|
|
628
|
+
"directory:search"
|
|
629
|
+
]
|
|
630
|
+
}
|
|
631
|
+
],
|
|
632
|
+
"parameters": [
|
|
633
|
+
{
|
|
634
|
+
"name": "q",
|
|
635
|
+
"in": "query",
|
|
636
|
+
"required": false,
|
|
637
|
+
"schema": {
|
|
638
|
+
"type": "string"
|
|
639
|
+
},
|
|
640
|
+
"description": "Query over name / display_name / github / telegram / member_id."
|
|
641
|
+
},
|
|
642
|
+
{
|
|
643
|
+
"name": "limit",
|
|
644
|
+
"in": "query",
|
|
645
|
+
"required": false,
|
|
646
|
+
"schema": {
|
|
647
|
+
"type": "integer",
|
|
648
|
+
"minimum": 1
|
|
649
|
+
}
|
|
650
|
+
}
|
|
651
|
+
],
|
|
652
|
+
"responses": {
|
|
653
|
+
"200": {
|
|
654
|
+
"description": "Privacy-graded search results.",
|
|
655
|
+
"content": {
|
|
656
|
+
"application/json": {
|
|
657
|
+
"schema": {
|
|
658
|
+
"$ref": "#/components/schemas/DirectorySearchResponse"
|
|
659
|
+
}
|
|
660
|
+
}
|
|
661
|
+
}
|
|
662
|
+
},
|
|
663
|
+
"401": {
|
|
664
|
+
"description": "No auth.",
|
|
665
|
+
"content": {
|
|
666
|
+
"application/json": {
|
|
667
|
+
"schema": {
|
|
668
|
+
"$ref": "#/components/schemas/Error"
|
|
669
|
+
}
|
|
670
|
+
}
|
|
671
|
+
}
|
|
672
|
+
},
|
|
673
|
+
"403": {
|
|
674
|
+
"description": "Scope not authorized.",
|
|
675
|
+
"content": {
|
|
676
|
+
"application/json": {
|
|
677
|
+
"schema": {
|
|
678
|
+
"$ref": "#/components/schemas/Error"
|
|
679
|
+
}
|
|
680
|
+
}
|
|
681
|
+
}
|
|
682
|
+
},
|
|
683
|
+
"500": {
|
|
684
|
+
"description": "Search failed.",
|
|
685
|
+
"content": {
|
|
686
|
+
"application/json": {
|
|
687
|
+
"schema": {
|
|
688
|
+
"$ref": "#/components/schemas/Error"
|
|
689
|
+
}
|
|
690
|
+
}
|
|
691
|
+
}
|
|
692
|
+
}
|
|
693
|
+
},
|
|
694
|
+
"x-ic-route": {
|
|
695
|
+
"file": "app/api/directory/search/route.ts",
|
|
696
|
+
"method": "GET"
|
|
697
|
+
}
|
|
698
|
+
}
|
|
699
|
+
},
|
|
700
|
+
"/api/resources/list": {
|
|
701
|
+
"get": {
|
|
702
|
+
"operationId": "listResources",
|
|
703
|
+
"tags": [
|
|
704
|
+
"resources"
|
|
705
|
+
],
|
|
706
|
+
"summary": "List bookable resources",
|
|
707
|
+
"description": "Clerk session or agt_ token with `resources:read`. Returns the resource catalog plus a staleness gauge.",
|
|
708
|
+
"security": [
|
|
709
|
+
{
|
|
710
|
+
"agentBearer": [
|
|
711
|
+
"resources:read"
|
|
712
|
+
]
|
|
713
|
+
}
|
|
714
|
+
],
|
|
715
|
+
"responses": {
|
|
716
|
+
"200": {
|
|
717
|
+
"description": "Bookable resources.",
|
|
718
|
+
"content": {
|
|
719
|
+
"application/json": {
|
|
720
|
+
"schema": {
|
|
721
|
+
"$ref": "#/components/schemas/ResourcesListResponse"
|
|
722
|
+
}
|
|
723
|
+
}
|
|
724
|
+
}
|
|
725
|
+
},
|
|
726
|
+
"401": {
|
|
727
|
+
"description": "No auth.",
|
|
728
|
+
"content": {
|
|
729
|
+
"application/json": {
|
|
730
|
+
"schema": {
|
|
731
|
+
"$ref": "#/components/schemas/Error"
|
|
732
|
+
}
|
|
733
|
+
}
|
|
734
|
+
}
|
|
735
|
+
},
|
|
736
|
+
"403": {
|
|
737
|
+
"description": "Scope not authorized.",
|
|
738
|
+
"content": {
|
|
739
|
+
"application/json": {
|
|
740
|
+
"schema": {
|
|
741
|
+
"$ref": "#/components/schemas/Error"
|
|
742
|
+
}
|
|
743
|
+
}
|
|
744
|
+
}
|
|
745
|
+
},
|
|
746
|
+
"500": {
|
|
747
|
+
"description": "Read failed.",
|
|
748
|
+
"content": {
|
|
749
|
+
"application/json": {
|
|
750
|
+
"schema": {
|
|
751
|
+
"$ref": "#/components/schemas/Error"
|
|
752
|
+
}
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
}
|
|
756
|
+
},
|
|
757
|
+
"x-ic-route": {
|
|
758
|
+
"file": "app/api/resources/list/route.ts",
|
|
759
|
+
"method": "GET"
|
|
760
|
+
}
|
|
761
|
+
}
|
|
762
|
+
},
|
|
763
|
+
"/api/resources/book": {
|
|
764
|
+
"post": {
|
|
765
|
+
"operationId": "bookResource",
|
|
766
|
+
"x-sandbox": "simulated",
|
|
767
|
+
"tags": [
|
|
768
|
+
"resources"
|
|
769
|
+
],
|
|
770
|
+
"summary": "Queue a resource booking",
|
|
771
|
+
"description": "Clerk session or agt_ token with `resources:book`. Queues a booking envelope (returns `queued`, not confirmed). IDEMPOTENT: a repeat within 30 days for the exact same start time is recognized (`was_dup: true`); an `Idempotency-Key` additionally replays the first result. Agent callers MUST supply `email`.",
|
|
772
|
+
"security": [
|
|
773
|
+
{
|
|
774
|
+
"agentBearer": [
|
|
775
|
+
"resources:book"
|
|
776
|
+
]
|
|
777
|
+
}
|
|
778
|
+
],
|
|
779
|
+
"parameters": [
|
|
780
|
+
{
|
|
781
|
+
"name": "Idempotency-Key",
|
|
782
|
+
"in": "header",
|
|
783
|
+
"required": false,
|
|
784
|
+
"schema": {
|
|
785
|
+
"type": "string",
|
|
786
|
+
"maxLength": 255
|
|
787
|
+
},
|
|
788
|
+
"description": "Optional. A retry carrying the same key replays the first successful result verbatim instead of creating a second side effect (honored by lib/idempotency.ts, 24h window). Complementary to each endpoint's own semantic dedupe. Absent = no replay."
|
|
789
|
+
}
|
|
790
|
+
],
|
|
791
|
+
"requestBody": {
|
|
792
|
+
"required": true,
|
|
793
|
+
"content": {
|
|
794
|
+
"application/json": {
|
|
795
|
+
"schema": {
|
|
796
|
+
"$ref": "#/components/schemas/BookRequest"
|
|
797
|
+
}
|
|
798
|
+
}
|
|
799
|
+
}
|
|
800
|
+
},
|
|
801
|
+
"responses": {
|
|
802
|
+
"200": {
|
|
803
|
+
"description": "Booking queued (or recognized as a duplicate).",
|
|
804
|
+
"content": {
|
|
805
|
+
"application/json": {
|
|
806
|
+
"schema": {
|
|
807
|
+
"$ref": "#/components/schemas/QueueResponse"
|
|
808
|
+
}
|
|
809
|
+
}
|
|
810
|
+
}
|
|
811
|
+
},
|
|
812
|
+
"400": {
|
|
813
|
+
"description": "Missing/invalid fields or missing email on the agent path.",
|
|
814
|
+
"content": {
|
|
815
|
+
"application/json": {
|
|
816
|
+
"schema": {
|
|
817
|
+
"$ref": "#/components/schemas/Error"
|
|
818
|
+
}
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
},
|
|
822
|
+
"401": {
|
|
823
|
+
"description": "No auth.",
|
|
824
|
+
"content": {
|
|
825
|
+
"application/json": {
|
|
826
|
+
"schema": {
|
|
827
|
+
"$ref": "#/components/schemas/Error"
|
|
828
|
+
}
|
|
829
|
+
}
|
|
830
|
+
}
|
|
831
|
+
},
|
|
832
|
+
"403": {
|
|
833
|
+
"description": "Scope/tier not authorized.",
|
|
834
|
+
"content": {
|
|
835
|
+
"application/json": {
|
|
836
|
+
"schema": {
|
|
837
|
+
"$ref": "#/components/schemas/Error"
|
|
838
|
+
}
|
|
839
|
+
}
|
|
840
|
+
}
|
|
841
|
+
},
|
|
842
|
+
"404": {
|
|
843
|
+
"description": "resource_id not found / not bookable.",
|
|
844
|
+
"content": {
|
|
845
|
+
"application/json": {
|
|
846
|
+
"schema": {
|
|
847
|
+
"$ref": "#/components/schemas/Error"
|
|
848
|
+
}
|
|
849
|
+
}
|
|
850
|
+
}
|
|
851
|
+
},
|
|
852
|
+
"413": {
|
|
853
|
+
"description": "Body exceeds 8KB.",
|
|
854
|
+
"content": {
|
|
855
|
+
"application/json": {
|
|
856
|
+
"schema": {
|
|
857
|
+
"$ref": "#/components/schemas/Error"
|
|
858
|
+
}
|
|
859
|
+
}
|
|
860
|
+
}
|
|
861
|
+
},
|
|
862
|
+
"429": {
|
|
863
|
+
"description": "Per-token rate limit exceeded.",
|
|
864
|
+
"content": {
|
|
865
|
+
"application/json": {
|
|
866
|
+
"schema": {
|
|
867
|
+
"$ref": "#/components/schemas/Error"
|
|
868
|
+
}
|
|
869
|
+
}
|
|
870
|
+
}
|
|
871
|
+
},
|
|
872
|
+
"500": {
|
|
873
|
+
"description": "KV write failed.",
|
|
874
|
+
"content": {
|
|
875
|
+
"application/json": {
|
|
876
|
+
"schema": {
|
|
877
|
+
"$ref": "#/components/schemas/Error"
|
|
878
|
+
}
|
|
879
|
+
}
|
|
880
|
+
}
|
|
881
|
+
}
|
|
882
|
+
},
|
|
883
|
+
"x-ic-route": {
|
|
884
|
+
"file": "app/api/resources/book/route.ts",
|
|
885
|
+
"method": "POST"
|
|
886
|
+
}
|
|
887
|
+
}
|
|
888
|
+
},
|
|
889
|
+
"/api/activity/me": {
|
|
890
|
+
"get": {
|
|
891
|
+
"operationId": "getMyActivity",
|
|
892
|
+
"tags": [
|
|
893
|
+
"account"
|
|
894
|
+
],
|
|
895
|
+
"summary": "Read the caller's own activity log",
|
|
896
|
+
"description": "Clerk session or agt_ token with `membership:read`. Returns the most recent consequential tool calls recorded for the caller.",
|
|
897
|
+
"security": [
|
|
898
|
+
{
|
|
899
|
+
"agentBearer": [
|
|
900
|
+
"membership:read"
|
|
901
|
+
]
|
|
902
|
+
}
|
|
903
|
+
],
|
|
904
|
+
"parameters": [
|
|
905
|
+
{
|
|
906
|
+
"name": "limit",
|
|
907
|
+
"in": "query",
|
|
908
|
+
"required": false,
|
|
909
|
+
"schema": {
|
|
910
|
+
"type": "integer",
|
|
911
|
+
"minimum": 1,
|
|
912
|
+
"maximum": 100
|
|
913
|
+
},
|
|
914
|
+
"description": "Default 25, max 100."
|
|
915
|
+
}
|
|
916
|
+
],
|
|
917
|
+
"responses": {
|
|
918
|
+
"200": {
|
|
919
|
+
"description": "Recent activity events.",
|
|
920
|
+
"content": {
|
|
921
|
+
"application/json": {
|
|
922
|
+
"schema": {
|
|
923
|
+
"$ref": "#/components/schemas/ActivityResponse"
|
|
924
|
+
}
|
|
925
|
+
}
|
|
926
|
+
}
|
|
927
|
+
},
|
|
928
|
+
"401": {
|
|
929
|
+
"description": "No auth.",
|
|
930
|
+
"content": {
|
|
931
|
+
"application/json": {
|
|
932
|
+
"schema": {
|
|
933
|
+
"$ref": "#/components/schemas/Error"
|
|
934
|
+
}
|
|
935
|
+
}
|
|
936
|
+
}
|
|
937
|
+
},
|
|
938
|
+
"403": {
|
|
939
|
+
"description": "Scope not authorized.",
|
|
940
|
+
"content": {
|
|
941
|
+
"application/json": {
|
|
942
|
+
"schema": {
|
|
943
|
+
"$ref": "#/components/schemas/Error"
|
|
944
|
+
}
|
|
945
|
+
}
|
|
946
|
+
}
|
|
947
|
+
}
|
|
948
|
+
},
|
|
949
|
+
"x-ic-route": {
|
|
950
|
+
"file": "app/api/activity/me/route.ts",
|
|
951
|
+
"method": "GET"
|
|
952
|
+
}
|
|
953
|
+
}
|
|
954
|
+
},
|
|
955
|
+
"/api/leaderboard/me": {
|
|
956
|
+
"get": {
|
|
957
|
+
"operationId": "getMyLeaderboardStatus",
|
|
958
|
+
"tags": [
|
|
959
|
+
"leaderboard"
|
|
960
|
+
],
|
|
961
|
+
"summary": "Read the caller's commit-leaderboard state",
|
|
962
|
+
"description": "Clerk session or agt_ token with `leaderboard:manage`. Returns opt-in flag, linked GitHub username, and current weekly rank if rendered.",
|
|
963
|
+
"security": [
|
|
964
|
+
{
|
|
965
|
+
"agentBearer": [
|
|
966
|
+
"leaderboard:manage"
|
|
967
|
+
]
|
|
968
|
+
}
|
|
969
|
+
],
|
|
970
|
+
"responses": {
|
|
971
|
+
"200": {
|
|
972
|
+
"description": "Leaderboard state for the caller.",
|
|
973
|
+
"content": {
|
|
974
|
+
"application/json": {
|
|
975
|
+
"schema": {
|
|
976
|
+
"$ref": "#/components/schemas/LeaderboardMeResponse"
|
|
977
|
+
}
|
|
978
|
+
}
|
|
979
|
+
}
|
|
980
|
+
},
|
|
981
|
+
"401": {
|
|
982
|
+
"description": "No auth.",
|
|
983
|
+
"content": {
|
|
984
|
+
"application/json": {
|
|
985
|
+
"schema": {
|
|
986
|
+
"$ref": "#/components/schemas/Error"
|
|
987
|
+
}
|
|
988
|
+
}
|
|
989
|
+
}
|
|
990
|
+
},
|
|
991
|
+
"403": {
|
|
992
|
+
"description": "Scope not authorized.",
|
|
993
|
+
"content": {
|
|
994
|
+
"application/json": {
|
|
995
|
+
"schema": {
|
|
996
|
+
"$ref": "#/components/schemas/Error"
|
|
997
|
+
}
|
|
998
|
+
}
|
|
999
|
+
}
|
|
1000
|
+
},
|
|
1001
|
+
"500": {
|
|
1002
|
+
"description": "Read failed.",
|
|
1003
|
+
"content": {
|
|
1004
|
+
"application/json": {
|
|
1005
|
+
"schema": {
|
|
1006
|
+
"$ref": "#/components/schemas/Error"
|
|
1007
|
+
}
|
|
1008
|
+
}
|
|
1009
|
+
}
|
|
1010
|
+
}
|
|
1011
|
+
},
|
|
1012
|
+
"x-ic-route": {
|
|
1013
|
+
"file": "app/api/leaderboard/me/route.ts",
|
|
1014
|
+
"method": "GET"
|
|
1015
|
+
}
|
|
1016
|
+
}
|
|
1017
|
+
},
|
|
1018
|
+
"/api/leaderboard/optin": {
|
|
1019
|
+
"post": {
|
|
1020
|
+
"operationId": "setLeaderboardOptIn",
|
|
1021
|
+
"x-sandbox": "simulated",
|
|
1022
|
+
"tags": [
|
|
1023
|
+
"leaderboard"
|
|
1024
|
+
],
|
|
1025
|
+
"summary": "Toggle commit-leaderboard opt-in",
|
|
1026
|
+
"description": "Clerk session or agt_ token with `leaderboard:manage`. Opting IN requires a linked GitHub identity (409 otherwise). Opting OUT is unconditional.",
|
|
1027
|
+
"security": [
|
|
1028
|
+
{
|
|
1029
|
+
"agentBearer": [
|
|
1030
|
+
"leaderboard:manage"
|
|
1031
|
+
]
|
|
1032
|
+
}
|
|
1033
|
+
],
|
|
1034
|
+
"requestBody": {
|
|
1035
|
+
"required": true,
|
|
1036
|
+
"content": {
|
|
1037
|
+
"application/json": {
|
|
1038
|
+
"schema": {
|
|
1039
|
+
"$ref": "#/components/schemas/LeaderboardOptInRequest"
|
|
1040
|
+
}
|
|
1041
|
+
}
|
|
1042
|
+
}
|
|
1043
|
+
},
|
|
1044
|
+
"responses": {
|
|
1045
|
+
"200": {
|
|
1046
|
+
"description": "New opt-in state.",
|
|
1047
|
+
"content": {
|
|
1048
|
+
"application/json": {
|
|
1049
|
+
"schema": {
|
|
1050
|
+
"$ref": "#/components/schemas/LeaderboardOptInResponse"
|
|
1051
|
+
}
|
|
1052
|
+
}
|
|
1053
|
+
}
|
|
1054
|
+
},
|
|
1055
|
+
"400": {
|
|
1056
|
+
"description": "Bad body.",
|
|
1057
|
+
"content": {
|
|
1058
|
+
"application/json": {
|
|
1059
|
+
"schema": {
|
|
1060
|
+
"$ref": "#/components/schemas/Error"
|
|
1061
|
+
}
|
|
1062
|
+
}
|
|
1063
|
+
}
|
|
1064
|
+
},
|
|
1065
|
+
"401": {
|
|
1066
|
+
"description": "No auth.",
|
|
1067
|
+
"content": {
|
|
1068
|
+
"application/json": {
|
|
1069
|
+
"schema": {
|
|
1070
|
+
"$ref": "#/components/schemas/Error"
|
|
1071
|
+
}
|
|
1072
|
+
}
|
|
1073
|
+
}
|
|
1074
|
+
},
|
|
1075
|
+
"403": {
|
|
1076
|
+
"description": "Scope/tier not authorized.",
|
|
1077
|
+
"content": {
|
|
1078
|
+
"application/json": {
|
|
1079
|
+
"schema": {
|
|
1080
|
+
"$ref": "#/components/schemas/Error"
|
|
1081
|
+
}
|
|
1082
|
+
}
|
|
1083
|
+
}
|
|
1084
|
+
},
|
|
1085
|
+
"409": {
|
|
1086
|
+
"description": "Opt-in requested but no GitHub link.",
|
|
1087
|
+
"content": {
|
|
1088
|
+
"application/json": {
|
|
1089
|
+
"schema": {
|
|
1090
|
+
"$ref": "#/components/schemas/Error"
|
|
1091
|
+
}
|
|
1092
|
+
}
|
|
1093
|
+
}
|
|
1094
|
+
},
|
|
1095
|
+
"500": {
|
|
1096
|
+
"description": "Clerk update failed.",
|
|
1097
|
+
"content": {
|
|
1098
|
+
"application/json": {
|
|
1099
|
+
"schema": {
|
|
1100
|
+
"$ref": "#/components/schemas/Error"
|
|
1101
|
+
}
|
|
1102
|
+
}
|
|
1103
|
+
}
|
|
1104
|
+
}
|
|
1105
|
+
},
|
|
1106
|
+
"x-ic-route": {
|
|
1107
|
+
"file": "app/api/leaderboard/optin/route.ts",
|
|
1108
|
+
"method": "POST"
|
|
1109
|
+
}
|
|
1110
|
+
}
|
|
1111
|
+
},
|
|
1112
|
+
"/api/research/ask": {
|
|
1113
|
+
"post": {
|
|
1114
|
+
"operationId": "askResearch",
|
|
1115
|
+
"x-sandbox": "real",
|
|
1116
|
+
"tags": [
|
|
1117
|
+
"research"
|
|
1118
|
+
],
|
|
1119
|
+
"summary": "Query the research RAG corpus",
|
|
1120
|
+
"description": "Clerk session or agt_ token with `research:query`. Forwards a top-k retrieval (optionally LLM-synthesized) query to the supercommons2 RAG funnel and returns the results. The query text is never logged. 60 requests/hour/member.",
|
|
1121
|
+
"security": [
|
|
1122
|
+
{
|
|
1123
|
+
"agentBearer": [
|
|
1124
|
+
"research:query"
|
|
1125
|
+
]
|
|
1126
|
+
}
|
|
1127
|
+
],
|
|
1128
|
+
"requestBody": {
|
|
1129
|
+
"required": true,
|
|
1130
|
+
"content": {
|
|
1131
|
+
"application/json": {
|
|
1132
|
+
"schema": {
|
|
1133
|
+
"$ref": "#/components/schemas/ResearchAskRequest"
|
|
1134
|
+
}
|
|
1135
|
+
}
|
|
1136
|
+
}
|
|
1137
|
+
},
|
|
1138
|
+
"responses": {
|
|
1139
|
+
"200": {
|
|
1140
|
+
"description": "Retrieval results (or a synthesized answer).",
|
|
1141
|
+
"content": {
|
|
1142
|
+
"application/json": {
|
|
1143
|
+
"schema": {
|
|
1144
|
+
"$ref": "#/components/schemas/ResearchAskResponse"
|
|
1145
|
+
}
|
|
1146
|
+
}
|
|
1147
|
+
}
|
|
1148
|
+
},
|
|
1149
|
+
"400": {
|
|
1150
|
+
"description": "Bad JSON / missing or oversized q / invalid k / invalid sources / invalid model.",
|
|
1151
|
+
"content": {
|
|
1152
|
+
"application/json": {
|
|
1153
|
+
"schema": {
|
|
1154
|
+
"$ref": "#/components/schemas/Error"
|
|
1155
|
+
}
|
|
1156
|
+
}
|
|
1157
|
+
}
|
|
1158
|
+
},
|
|
1159
|
+
"401": {
|
|
1160
|
+
"description": "No auth.",
|
|
1161
|
+
"content": {
|
|
1162
|
+
"application/json": {
|
|
1163
|
+
"schema": {
|
|
1164
|
+
"$ref": "#/components/schemas/Error"
|
|
1165
|
+
}
|
|
1166
|
+
}
|
|
1167
|
+
}
|
|
1168
|
+
},
|
|
1169
|
+
"403": {
|
|
1170
|
+
"description": "Scope/tier not authorized.",
|
|
1171
|
+
"content": {
|
|
1172
|
+
"application/json": {
|
|
1173
|
+
"schema": {
|
|
1174
|
+
"$ref": "#/components/schemas/Error"
|
|
1175
|
+
}
|
|
1176
|
+
}
|
|
1177
|
+
}
|
|
1178
|
+
},
|
|
1179
|
+
"429": {
|
|
1180
|
+
"description": "Per-member hourly rate budget exceeded.",
|
|
1181
|
+
"content": {
|
|
1182
|
+
"application/json": {
|
|
1183
|
+
"schema": {
|
|
1184
|
+
"$ref": "#/components/schemas/Error"
|
|
1185
|
+
}
|
|
1186
|
+
}
|
|
1187
|
+
}
|
|
1188
|
+
},
|
|
1189
|
+
"502": {
|
|
1190
|
+
"description": "Upstream RAG funnel error.",
|
|
1191
|
+
"content": {
|
|
1192
|
+
"application/json": {
|
|
1193
|
+
"schema": {
|
|
1194
|
+
"$ref": "#/components/schemas/Error"
|
|
1195
|
+
}
|
|
1196
|
+
}
|
|
1197
|
+
}
|
|
1198
|
+
},
|
|
1199
|
+
"503": {
|
|
1200
|
+
"description": "RAG funnel not configured / rate limiter unavailable.",
|
|
1201
|
+
"content": {
|
|
1202
|
+
"application/json": {
|
|
1203
|
+
"schema": {
|
|
1204
|
+
"$ref": "#/components/schemas/Error"
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1207
|
+
}
|
|
1208
|
+
},
|
|
1209
|
+
"504": {
|
|
1210
|
+
"description": "Upstream RAG funnel timeout.",
|
|
1211
|
+
"content": {
|
|
1212
|
+
"application/json": {
|
|
1213
|
+
"schema": {
|
|
1214
|
+
"$ref": "#/components/schemas/Error"
|
|
1215
|
+
}
|
|
1216
|
+
}
|
|
1217
|
+
}
|
|
1218
|
+
}
|
|
1219
|
+
},
|
|
1220
|
+
"x-ic-route": {
|
|
1221
|
+
"file": "app/api/research/ask/route.ts",
|
|
1222
|
+
"method": "POST"
|
|
1223
|
+
}
|
|
1224
|
+
}
|
|
1225
|
+
},
|
|
1226
|
+
"/api/ingest/highlights/pending": {
|
|
1227
|
+
"post": {
|
|
1228
|
+
"operationId": "submitHighlightPending",
|
|
1229
|
+
"x-sandbox": "simulated",
|
|
1230
|
+
"tags": [
|
|
1231
|
+
"highlights"
|
|
1232
|
+
],
|
|
1233
|
+
"summary": "Submit a highlight to the moderation queue",
|
|
1234
|
+
"description": "agt_ token required (scope `events:submit_recap`). Adds a HighlightStory to the pending moderation queue; an operator approves it. ASYNC-JOB: returns 202 Accepted with `status: pending`, a `job_id` (= the story `id`), a `poll_url`, and a `Location` response header — all pointing at `GET /api/ingest/highlights/pending?id=<job_id>`, which returns `status: pending` while queued or `status: gone` once it leaves the queue (approved → active, rejected, or expired). IDEMPOTENT: re-submitting the same story `id` refreshes the pending record without bumping the rate counter; an `Idempotency-Key` additionally replays the 202 (with the same `Location`). Rate: 3/token/UTC day.",
|
|
1235
|
+
"security": [
|
|
1236
|
+
{
|
|
1237
|
+
"agentBearer": [
|
|
1238
|
+
"events:submit_recap"
|
|
1239
|
+
]
|
|
1240
|
+
}
|
|
1241
|
+
],
|
|
1242
|
+
"parameters": [
|
|
1243
|
+
{
|
|
1244
|
+
"name": "Idempotency-Key",
|
|
1245
|
+
"in": "header",
|
|
1246
|
+
"required": false,
|
|
1247
|
+
"schema": {
|
|
1248
|
+
"type": "string",
|
|
1249
|
+
"maxLength": 255
|
|
1250
|
+
},
|
|
1251
|
+
"description": "Optional. A retry carrying the same key replays the first successful result verbatim instead of creating a second side effect (honored by lib/idempotency.ts, 24h window). Complementary to each endpoint's own semantic dedupe. Absent = no replay."
|
|
1252
|
+
}
|
|
1253
|
+
],
|
|
1254
|
+
"requestBody": {
|
|
1255
|
+
"required": true,
|
|
1256
|
+
"content": {
|
|
1257
|
+
"application/json": {
|
|
1258
|
+
"schema": {
|
|
1259
|
+
"$ref": "#/components/schemas/HighlightPendingRequest"
|
|
1260
|
+
}
|
|
1261
|
+
}
|
|
1262
|
+
}
|
|
1263
|
+
},
|
|
1264
|
+
"responses": {
|
|
1265
|
+
"202": {
|
|
1266
|
+
"description": "Accepted into the pending queue. Poll the `Location` header (or `poll_url`) for the job's status.",
|
|
1267
|
+
"headers": {
|
|
1268
|
+
"Location": {
|
|
1269
|
+
"description": "Status-poll URL for this submission: GET /api/ingest/highlights/pending?id=<job_id> → { status: pending | gone }.",
|
|
1270
|
+
"schema": {
|
|
1271
|
+
"type": "string"
|
|
1272
|
+
}
|
|
1273
|
+
}
|
|
1274
|
+
},
|
|
1275
|
+
"content": {
|
|
1276
|
+
"application/json": {
|
|
1277
|
+
"schema": {
|
|
1278
|
+
"$ref": "#/components/schemas/HighlightPendingResponse"
|
|
1279
|
+
}
|
|
1280
|
+
}
|
|
1281
|
+
}
|
|
1282
|
+
},
|
|
1283
|
+
"400": {
|
|
1284
|
+
"description": "Invalid JSON or story validation error.",
|
|
1285
|
+
"content": {
|
|
1286
|
+
"application/json": {
|
|
1287
|
+
"schema": {
|
|
1288
|
+
"$ref": "#/components/schemas/Error"
|
|
1289
|
+
}
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
},
|
|
1293
|
+
"401": {
|
|
1294
|
+
"description": "Missing/invalid token.",
|
|
1295
|
+
"content": {
|
|
1296
|
+
"application/json": {
|
|
1297
|
+
"schema": {
|
|
1298
|
+
"$ref": "#/components/schemas/Error"
|
|
1299
|
+
}
|
|
1300
|
+
}
|
|
1301
|
+
}
|
|
1302
|
+
},
|
|
1303
|
+
"413": {
|
|
1304
|
+
"description": "Body too large.",
|
|
1305
|
+
"content": {
|
|
1306
|
+
"application/json": {
|
|
1307
|
+
"schema": {
|
|
1308
|
+
"$ref": "#/components/schemas/Error"
|
|
1309
|
+
}
|
|
1310
|
+
}
|
|
1311
|
+
}
|
|
1312
|
+
},
|
|
1313
|
+
"429": {
|
|
1314
|
+
"description": "Per-token daily rate limit exceeded.",
|
|
1315
|
+
"content": {
|
|
1316
|
+
"application/json": {
|
|
1317
|
+
"schema": {
|
|
1318
|
+
"$ref": "#/components/schemas/Error"
|
|
1319
|
+
}
|
|
1320
|
+
}
|
|
1321
|
+
}
|
|
1322
|
+
},
|
|
1323
|
+
"500": {
|
|
1324
|
+
"description": "Enqueue failed.",
|
|
1325
|
+
"content": {
|
|
1326
|
+
"application/json": {
|
|
1327
|
+
"schema": {
|
|
1328
|
+
"$ref": "#/components/schemas/Error"
|
|
1329
|
+
}
|
|
1330
|
+
}
|
|
1331
|
+
}
|
|
1332
|
+
}
|
|
1333
|
+
},
|
|
1334
|
+
"x-ic-route": {
|
|
1335
|
+
"file": "app/api/ingest/highlights/pending/route.ts",
|
|
1336
|
+
"method": "POST"
|
|
1337
|
+
}
|
|
1338
|
+
}
|
|
1339
|
+
},
|
|
1340
|
+
"/api/agent/feedback": {
|
|
1341
|
+
"post": {
|
|
1342
|
+
"operationId": "submitFeedback",
|
|
1343
|
+
"x-sandbox": "real",
|
|
1344
|
+
"tags": [
|
|
1345
|
+
"feedback"
|
|
1346
|
+
],
|
|
1347
|
+
"summary": "File feedback, a feature request, or a breakage report",
|
|
1348
|
+
"description": "Anonymous-OK (per-IP rate limited, 10/hr). An optional agt_ Bearer (`feedback:submit`) attributes the ticket to your account; a bad token is treated as anonymous rather than refused (low-friction channel).",
|
|
1349
|
+
"security": [
|
|
1350
|
+
{},
|
|
1351
|
+
{
|
|
1352
|
+
"agentBearer": [
|
|
1353
|
+
"feedback:submit"
|
|
1354
|
+
]
|
|
1355
|
+
}
|
|
1356
|
+
],
|
|
1357
|
+
"requestBody": {
|
|
1358
|
+
"required": true,
|
|
1359
|
+
"content": {
|
|
1360
|
+
"application/json": {
|
|
1361
|
+
"schema": {
|
|
1362
|
+
"$ref": "#/components/schemas/FeedbackSubmitRequest"
|
|
1363
|
+
}
|
|
1364
|
+
}
|
|
1365
|
+
}
|
|
1366
|
+
},
|
|
1367
|
+
"responses": {
|
|
1368
|
+
"200": {
|
|
1369
|
+
"description": "Ticket accepted.",
|
|
1370
|
+
"content": {
|
|
1371
|
+
"application/json": {
|
|
1372
|
+
"schema": {
|
|
1373
|
+
"$ref": "#/components/schemas/FeedbackSubmitResponse"
|
|
1374
|
+
}
|
|
1375
|
+
}
|
|
1376
|
+
}
|
|
1377
|
+
},
|
|
1378
|
+
"400": {
|
|
1379
|
+
"description": "Empty body, invalid JSON, invalid kind, or validation failure.",
|
|
1380
|
+
"content": {
|
|
1381
|
+
"application/json": {
|
|
1382
|
+
"schema": {
|
|
1383
|
+
"$ref": "#/components/schemas/Error"
|
|
1384
|
+
}
|
|
1385
|
+
}
|
|
1386
|
+
}
|
|
1387
|
+
},
|
|
1388
|
+
"429": {
|
|
1389
|
+
"description": "Per-IP hourly rate limit exceeded.",
|
|
1390
|
+
"content": {
|
|
1391
|
+
"application/json": {
|
|
1392
|
+
"schema": {
|
|
1393
|
+
"$ref": "#/components/schemas/Error"
|
|
1394
|
+
}
|
|
1395
|
+
}
|
|
1396
|
+
}
|
|
1397
|
+
},
|
|
1398
|
+
"500": {
|
|
1399
|
+
"description": "KV write failed.",
|
|
1400
|
+
"content": {
|
|
1401
|
+
"application/json": {
|
|
1402
|
+
"schema": {
|
|
1403
|
+
"$ref": "#/components/schemas/Error"
|
|
1404
|
+
}
|
|
1405
|
+
}
|
|
1406
|
+
}
|
|
1407
|
+
}
|
|
1408
|
+
},
|
|
1409
|
+
"x-ic-route": {
|
|
1410
|
+
"file": "app/api/agent/feedback/route.ts",
|
|
1411
|
+
"method": "POST"
|
|
1412
|
+
}
|
|
1413
|
+
}
|
|
1414
|
+
},
|
|
1415
|
+
"/api/agent/token/revoke": {
|
|
1416
|
+
"post": {
|
|
1417
|
+
"operationId": "revokeOwnToken",
|
|
1418
|
+
"x-sandbox": "real",
|
|
1419
|
+
"tags": [
|
|
1420
|
+
"auth"
|
|
1421
|
+
],
|
|
1422
|
+
"summary": "Self-revoke the presenting token",
|
|
1423
|
+
"description": "agt_ token required. The presented token revokes ITSELF (self-destruction, not privilege escalation) — it cannot revoke other tokens. Idempotent: re-revoking an already-revoked token returns `already_revoked: true`.",
|
|
1424
|
+
"security": [
|
|
1425
|
+
{
|
|
1426
|
+
"agentBearer": []
|
|
1427
|
+
}
|
|
1428
|
+
],
|
|
1429
|
+
"responses": {
|
|
1430
|
+
"200": {
|
|
1431
|
+
"description": "Token revoked.",
|
|
1432
|
+
"content": {
|
|
1433
|
+
"application/json": {
|
|
1434
|
+
"schema": {
|
|
1435
|
+
"$ref": "#/components/schemas/TokenRevokeResponse"
|
|
1436
|
+
}
|
|
1437
|
+
}
|
|
1438
|
+
}
|
|
1439
|
+
},
|
|
1440
|
+
"401": {
|
|
1441
|
+
"description": "Missing/malformed/unknown/already-revoked token.",
|
|
1442
|
+
"content": {
|
|
1443
|
+
"application/json": {
|
|
1444
|
+
"schema": {
|
|
1445
|
+
"$ref": "#/components/schemas/Error"
|
|
1446
|
+
}
|
|
1447
|
+
}
|
|
1448
|
+
}
|
|
1449
|
+
},
|
|
1450
|
+
"500": {
|
|
1451
|
+
"description": "KV write failed (safe to retry).",
|
|
1452
|
+
"content": {
|
|
1453
|
+
"application/json": {
|
|
1454
|
+
"schema": {
|
|
1455
|
+
"$ref": "#/components/schemas/Error"
|
|
1456
|
+
}
|
|
1457
|
+
}
|
|
1458
|
+
}
|
|
1459
|
+
}
|
|
1460
|
+
},
|
|
1461
|
+
"x-ic-route": {
|
|
1462
|
+
"file": "app/api/agent/token/revoke/route.ts",
|
|
1463
|
+
"method": "POST"
|
|
1464
|
+
}
|
|
1465
|
+
}
|
|
1466
|
+
},
|
|
1467
|
+
"/api/agent/setup-check": {
|
|
1468
|
+
"get": {
|
|
1469
|
+
"operationId": "setupCheck",
|
|
1470
|
+
"tags": [
|
|
1471
|
+
"auth"
|
|
1472
|
+
],
|
|
1473
|
+
"summary": "Deterministic 'am I set up?' probe",
|
|
1474
|
+
"description": "Optional Bearer. Always 200. With a valid token, returns `ready: true` plus scopes + the MCP install recipe; without (or with a bad token), returns `ready: false` + `missing` + `next_actions`. The verdict is the body, not the HTTP status.",
|
|
1475
|
+
"security": [
|
|
1476
|
+
{},
|
|
1477
|
+
{
|
|
1478
|
+
"agentBearer": []
|
|
1479
|
+
}
|
|
1480
|
+
],
|
|
1481
|
+
"responses": {
|
|
1482
|
+
"200": {
|
|
1483
|
+
"description": "A setup checklist (ready true/false).",
|
|
1484
|
+
"content": {
|
|
1485
|
+
"application/json": {
|
|
1486
|
+
"schema": {
|
|
1487
|
+
"$ref": "#/components/schemas/SetupCheckResponse"
|
|
1488
|
+
}
|
|
1489
|
+
}
|
|
1490
|
+
}
|
|
1491
|
+
}
|
|
1492
|
+
},
|
|
1493
|
+
"x-ic-route": {
|
|
1494
|
+
"file": "app/api/agent/setup-check/route.ts",
|
|
1495
|
+
"method": "GET"
|
|
1496
|
+
}
|
|
1497
|
+
}
|
|
1498
|
+
},
|
|
1499
|
+
"/api/agent/signup/start": {
|
|
1500
|
+
"post": {
|
|
1501
|
+
"operationId": "startSignup",
|
|
1502
|
+
"tags": [
|
|
1503
|
+
"auth"
|
|
1504
|
+
],
|
|
1505
|
+
"summary": "Begin the RFC 8628 device-code token mint",
|
|
1506
|
+
"description": "Anonymous (per-IP rate limited, 30/hr). Returns a device_code (kept by the agent) + a user_code the human enters at verify_url. Then poll /api/agent/signup/poll until the human approves.",
|
|
1507
|
+
"security": [
|
|
1508
|
+
{}
|
|
1509
|
+
],
|
|
1510
|
+
"requestBody": {
|
|
1511
|
+
"required": true,
|
|
1512
|
+
"content": {
|
|
1513
|
+
"application/json": {
|
|
1514
|
+
"schema": {
|
|
1515
|
+
"$ref": "#/components/schemas/SignupStartRequest"
|
|
1516
|
+
}
|
|
1517
|
+
}
|
|
1518
|
+
}
|
|
1519
|
+
},
|
|
1520
|
+
"responses": {
|
|
1521
|
+
"200": {
|
|
1522
|
+
"description": "Device-code grant started.",
|
|
1523
|
+
"content": {
|
|
1524
|
+
"application/json": {
|
|
1525
|
+
"schema": {
|
|
1526
|
+
"$ref": "#/components/schemas/SignupStartResponse"
|
|
1527
|
+
}
|
|
1528
|
+
}
|
|
1529
|
+
}
|
|
1530
|
+
},
|
|
1531
|
+
"400": {
|
|
1532
|
+
"description": "Missing/invalid scopes or malformed body.",
|
|
1533
|
+
"content": {
|
|
1534
|
+
"application/json": {
|
|
1535
|
+
"schema": {
|
|
1536
|
+
"$ref": "#/components/schemas/Error"
|
|
1537
|
+
}
|
|
1538
|
+
}
|
|
1539
|
+
}
|
|
1540
|
+
},
|
|
1541
|
+
"429": {
|
|
1542
|
+
"description": "Per-IP rate limit exceeded.",
|
|
1543
|
+
"content": {
|
|
1544
|
+
"application/json": {
|
|
1545
|
+
"schema": {
|
|
1546
|
+
"$ref": "#/components/schemas/Error"
|
|
1547
|
+
}
|
|
1548
|
+
}
|
|
1549
|
+
}
|
|
1550
|
+
},
|
|
1551
|
+
"500": {
|
|
1552
|
+
"description": "KV write failed.",
|
|
1553
|
+
"content": {
|
|
1554
|
+
"application/json": {
|
|
1555
|
+
"schema": {
|
|
1556
|
+
"$ref": "#/components/schemas/Error"
|
|
1557
|
+
}
|
|
1558
|
+
}
|
|
1559
|
+
}
|
|
1560
|
+
}
|
|
1561
|
+
},
|
|
1562
|
+
"x-ic-route": {
|
|
1563
|
+
"file": "app/api/agent/signup/start/route.ts",
|
|
1564
|
+
"method": "POST"
|
|
1565
|
+
}
|
|
1566
|
+
}
|
|
1567
|
+
},
|
|
1568
|
+
"/api/agent/signup/poll": {
|
|
1569
|
+
"get": {
|
|
1570
|
+
"operationId": "pollSignup",
|
|
1571
|
+
"tags": [
|
|
1572
|
+
"auth"
|
|
1573
|
+
],
|
|
1574
|
+
"summary": "Poll a device-code grant for completion",
|
|
1575
|
+
"description": "Anonymous (the device_code is the credential). Returns `pending`, `completed` (with the minted agent_token — surfaced ONCE), or `cancelled`. After completion the record is consumed and further polls 410.",
|
|
1576
|
+
"security": [
|
|
1577
|
+
{}
|
|
1578
|
+
],
|
|
1579
|
+
"parameters": [
|
|
1580
|
+
{
|
|
1581
|
+
"name": "device_code",
|
|
1582
|
+
"in": "query",
|
|
1583
|
+
"required": false,
|
|
1584
|
+
"schema": {
|
|
1585
|
+
"type": "string",
|
|
1586
|
+
"minLength": 16,
|
|
1587
|
+
"maxLength": 64
|
|
1588
|
+
},
|
|
1589
|
+
"description": "The device_code from /start. Omit for the self-describe contract."
|
|
1590
|
+
}
|
|
1591
|
+
],
|
|
1592
|
+
"responses": {
|
|
1593
|
+
"200": {
|
|
1594
|
+
"description": "Grant status (pending/completed/cancelled) or the self-describe contract.",
|
|
1595
|
+
"content": {
|
|
1596
|
+
"application/json": {
|
|
1597
|
+
"schema": {
|
|
1598
|
+
"$ref": "#/components/schemas/SignupPollResponse"
|
|
1599
|
+
}
|
|
1600
|
+
}
|
|
1601
|
+
}
|
|
1602
|
+
},
|
|
1603
|
+
"410": {
|
|
1604
|
+
"description": "device_code expired, unknown, consumed, or cancelled-and-already-surfaced.",
|
|
1605
|
+
"content": {
|
|
1606
|
+
"application/json": {
|
|
1607
|
+
"schema": {
|
|
1608
|
+
"$ref": "#/components/schemas/Error"
|
|
1609
|
+
}
|
|
1610
|
+
}
|
|
1611
|
+
}
|
|
1612
|
+
},
|
|
1613
|
+
"500": {
|
|
1614
|
+
"description": "Completed record missing token.",
|
|
1615
|
+
"content": {
|
|
1616
|
+
"application/json": {
|
|
1617
|
+
"schema": {
|
|
1618
|
+
"$ref": "#/components/schemas/Error"
|
|
1619
|
+
}
|
|
1620
|
+
}
|
|
1621
|
+
}
|
|
1622
|
+
}
|
|
1623
|
+
},
|
|
1624
|
+
"x-ic-route": {
|
|
1625
|
+
"file": "app/api/agent/signup/poll/route.ts",
|
|
1626
|
+
"method": "GET"
|
|
1627
|
+
}
|
|
1628
|
+
}
|
|
1629
|
+
},
|
|
1630
|
+
"/api/floor10/donations": {
|
|
1631
|
+
"get": {
|
|
1632
|
+
"operationId": "getDonorWall",
|
|
1633
|
+
"tags": [
|
|
1634
|
+
"payments"
|
|
1635
|
+
],
|
|
1636
|
+
"summary": "Read the public donor wall",
|
|
1637
|
+
"description": "Public, no auth. Running total raised (USDC), donor count, and recent settled gifts. Donations are made via the x402 pay-per-use surface (see the x-payment-info discovery pointer at the top of this document).",
|
|
1638
|
+
"security": [
|
|
1639
|
+
{}
|
|
1640
|
+
],
|
|
1641
|
+
"parameters": [
|
|
1642
|
+
{
|
|
1643
|
+
"name": "limit",
|
|
1644
|
+
"in": "query",
|
|
1645
|
+
"required": false,
|
|
1646
|
+
"schema": {
|
|
1647
|
+
"type": "integer",
|
|
1648
|
+
"minimum": 1,
|
|
1649
|
+
"maximum": 50
|
|
1650
|
+
},
|
|
1651
|
+
"description": "Recent-donor cap; default 10, max 50."
|
|
1652
|
+
}
|
|
1653
|
+
],
|
|
1654
|
+
"responses": {
|
|
1655
|
+
"200": {
|
|
1656
|
+
"description": "The donor wall.",
|
|
1657
|
+
"content": {
|
|
1658
|
+
"application/json": {
|
|
1659
|
+
"schema": {
|
|
1660
|
+
"$ref": "#/components/schemas/DonationsResponse"
|
|
1661
|
+
}
|
|
1662
|
+
}
|
|
1663
|
+
}
|
|
1664
|
+
}
|
|
1665
|
+
},
|
|
1666
|
+
"x-ic-route": {
|
|
1667
|
+
"file": "app/api/floor10/donations/route.ts",
|
|
1668
|
+
"method": "GET"
|
|
1669
|
+
}
|
|
1670
|
+
}
|
|
1671
|
+
},
|
|
1672
|
+
"/api/tier/me": {
|
|
1673
|
+
"get": {
|
|
1674
|
+
"operationId": "getMyTier",
|
|
1675
|
+
"tags": [
|
|
1676
|
+
"membership",
|
|
1677
|
+
"browser-session"
|
|
1678
|
+
],
|
|
1679
|
+
"summary": "Read the caller's membership tier",
|
|
1680
|
+
"description": "Clerk-session only (NOT reachable with an agt_ bearer). Returns the caller's current tier, any pending request, and history. Agents read their tier via the MCP tool `ic_get_my_membership`.",
|
|
1681
|
+
"security": [
|
|
1682
|
+
{
|
|
1683
|
+
"clerkSession": []
|
|
1684
|
+
}
|
|
1685
|
+
],
|
|
1686
|
+
"responses": {
|
|
1687
|
+
"200": {
|
|
1688
|
+
"description": "Tier + pending request + history.",
|
|
1689
|
+
"content": {
|
|
1690
|
+
"application/json": {
|
|
1691
|
+
"schema": {
|
|
1692
|
+
"$ref": "#/components/schemas/TierMeResponse"
|
|
1693
|
+
}
|
|
1694
|
+
}
|
|
1695
|
+
}
|
|
1696
|
+
},
|
|
1697
|
+
"401": {
|
|
1698
|
+
"description": "Not signed in.",
|
|
1699
|
+
"content": {
|
|
1700
|
+
"application/json": {
|
|
1701
|
+
"schema": {
|
|
1702
|
+
"$ref": "#/components/schemas/Error"
|
|
1703
|
+
}
|
|
1704
|
+
}
|
|
1705
|
+
}
|
|
1706
|
+
},
|
|
1707
|
+
"500": {
|
|
1708
|
+
"description": "Clerk lookup failed.",
|
|
1709
|
+
"content": {
|
|
1710
|
+
"application/json": {
|
|
1711
|
+
"schema": {
|
|
1712
|
+
"$ref": "#/components/schemas/Error"
|
|
1713
|
+
}
|
|
1714
|
+
}
|
|
1715
|
+
}
|
|
1716
|
+
}
|
|
1717
|
+
},
|
|
1718
|
+
"x-ic-route": {
|
|
1719
|
+
"file": "app/api/tier/me/route.ts",
|
|
1720
|
+
"method": "GET"
|
|
1721
|
+
}
|
|
1722
|
+
}
|
|
1723
|
+
},
|
|
1724
|
+
"/api/tier/request": {
|
|
1725
|
+
"post": {
|
|
1726
|
+
"operationId": "requestTier",
|
|
1727
|
+
"tags": [
|
|
1728
|
+
"membership",
|
|
1729
|
+
"browser-session"
|
|
1730
|
+
],
|
|
1731
|
+
"summary": "Request a higher membership tier",
|
|
1732
|
+
"description": "Clerk-session only (NOT reachable with an agt_ bearer). Records a pending request for a higher, self-requestable ring; an operator approves it. Idempotent: re-posting overwrites the prior pending request. Agents use the MCP tool `ic_request_tier`.",
|
|
1733
|
+
"security": [
|
|
1734
|
+
{
|
|
1735
|
+
"clerkSession": []
|
|
1736
|
+
}
|
|
1737
|
+
],
|
|
1738
|
+
"requestBody": {
|
|
1739
|
+
"required": true,
|
|
1740
|
+
"content": {
|
|
1741
|
+
"application/json": {
|
|
1742
|
+
"schema": {
|
|
1743
|
+
"$ref": "#/components/schemas/TierRequestRequest"
|
|
1744
|
+
}
|
|
1745
|
+
}
|
|
1746
|
+
}
|
|
1747
|
+
},
|
|
1748
|
+
"responses": {
|
|
1749
|
+
"200": {
|
|
1750
|
+
"description": "Request recorded.",
|
|
1751
|
+
"content": {
|
|
1752
|
+
"application/json": {
|
|
1753
|
+
"schema": {
|
|
1754
|
+
"$ref": "#/components/schemas/TierRequestResponse"
|
|
1755
|
+
}
|
|
1756
|
+
}
|
|
1757
|
+
}
|
|
1758
|
+
},
|
|
1759
|
+
"400": {
|
|
1760
|
+
"description": "Invalid tier (not self-requestable / not higher than current).",
|
|
1761
|
+
"content": {
|
|
1762
|
+
"application/json": {
|
|
1763
|
+
"schema": {
|
|
1764
|
+
"$ref": "#/components/schemas/Error"
|
|
1765
|
+
}
|
|
1766
|
+
}
|
|
1767
|
+
}
|
|
1768
|
+
},
|
|
1769
|
+
"401": {
|
|
1770
|
+
"description": "Not signed in.",
|
|
1771
|
+
"content": {
|
|
1772
|
+
"application/json": {
|
|
1773
|
+
"schema": {
|
|
1774
|
+
"$ref": "#/components/schemas/Error"
|
|
1775
|
+
}
|
|
1776
|
+
}
|
|
1777
|
+
}
|
|
1778
|
+
},
|
|
1779
|
+
"500": {
|
|
1780
|
+
"description": "Clerk update failed.",
|
|
1781
|
+
"content": {
|
|
1782
|
+
"application/json": {
|
|
1783
|
+
"schema": {
|
|
1784
|
+
"$ref": "#/components/schemas/Error"
|
|
1785
|
+
}
|
|
1786
|
+
}
|
|
1787
|
+
}
|
|
1788
|
+
}
|
|
1789
|
+
},
|
|
1790
|
+
"x-ic-route": {
|
|
1791
|
+
"file": "app/api/tier/request/route.ts",
|
|
1792
|
+
"method": "POST"
|
|
1793
|
+
}
|
|
1794
|
+
},
|
|
1795
|
+
"delete": {
|
|
1796
|
+
"operationId": "cancelTierRequest",
|
|
1797
|
+
"tags": [
|
|
1798
|
+
"membership",
|
|
1799
|
+
"browser-session"
|
|
1800
|
+
],
|
|
1801
|
+
"summary": "Cancel the pending tier request",
|
|
1802
|
+
"description": "Clerk-session only. Clears the caller's pending tier request. No-op if none is pending.",
|
|
1803
|
+
"security": [
|
|
1804
|
+
{
|
|
1805
|
+
"clerkSession": []
|
|
1806
|
+
}
|
|
1807
|
+
],
|
|
1808
|
+
"responses": {
|
|
1809
|
+
"200": {
|
|
1810
|
+
"description": "Cancelled (or nothing was pending).",
|
|
1811
|
+
"content": {
|
|
1812
|
+
"application/json": {
|
|
1813
|
+
"schema": {
|
|
1814
|
+
"$ref": "#/components/schemas/TierRequestCancelResponse"
|
|
1815
|
+
}
|
|
1816
|
+
}
|
|
1817
|
+
}
|
|
1818
|
+
},
|
|
1819
|
+
"401": {
|
|
1820
|
+
"description": "Not signed in.",
|
|
1821
|
+
"content": {
|
|
1822
|
+
"application/json": {
|
|
1823
|
+
"schema": {
|
|
1824
|
+
"$ref": "#/components/schemas/Error"
|
|
1825
|
+
}
|
|
1826
|
+
}
|
|
1827
|
+
}
|
|
1828
|
+
},
|
|
1829
|
+
"500": {
|
|
1830
|
+
"description": "Clerk update failed.",
|
|
1831
|
+
"content": {
|
|
1832
|
+
"application/json": {
|
|
1833
|
+
"schema": {
|
|
1834
|
+
"$ref": "#/components/schemas/Error"
|
|
1835
|
+
}
|
|
1836
|
+
}
|
|
1837
|
+
}
|
|
1838
|
+
}
|
|
1839
|
+
},
|
|
1840
|
+
"x-ic-route": {
|
|
1841
|
+
"file": "app/api/tier/request/route.ts",
|
|
1842
|
+
"method": "DELETE"
|
|
1843
|
+
}
|
|
1844
|
+
}
|
|
1845
|
+
}
|
|
1846
|
+
},
|
|
1847
|
+
"components": {
|
|
1848
|
+
"securitySchemes": {
|
|
1849
|
+
"agentBearer": {
|
|
1850
|
+
"type": "http",
|
|
1851
|
+
"scheme": "bearer",
|
|
1852
|
+
"bearerFormat": "agt_<base64url>",
|
|
1853
|
+
"description": "Per-member, individually-revocable agent token minted via the device-code flow. Send as `Authorization: Bearer agt_...`. The scope array in each operation's security requirement names the IC scope the handler enforces."
|
|
1854
|
+
},
|
|
1855
|
+
"clerkSession": {
|
|
1856
|
+
"type": "apiKey",
|
|
1857
|
+
"in": "cookie",
|
|
1858
|
+
"name": "__session",
|
|
1859
|
+
"description": "Browser Clerk session cookie. Operations under this scheme are reachable ONLY from a signed-in browser session, NOT with an agt_ bearer token. Agents use the equivalent MCP tools (e.g. ic_get_my_membership, ic_request_tier)."
|
|
1860
|
+
}
|
|
1861
|
+
},
|
|
1862
|
+
"schemas": {
|
|
1863
|
+
"Error": {
|
|
1864
|
+
"type": "object",
|
|
1865
|
+
"required": [
|
|
1866
|
+
"error"
|
|
1867
|
+
],
|
|
1868
|
+
"additionalProperties": true,
|
|
1869
|
+
"description": "Structured JSON error. `error` (string) is always present — an error code or a human-readable message. `ok:false` is present on bearer auth-gate rejections. Endpoints may attach additional context keys to aid recovery (tier, current_tier, limit, window_seconds, valid_kinds, recovery_hint, detail, example, ...); the reusable ones are named below.",
|
|
1870
|
+
"properties": {
|
|
1871
|
+
"error": {
|
|
1872
|
+
"type": "string",
|
|
1873
|
+
"description": "Error code or human-readable message (always present)."
|
|
1874
|
+
},
|
|
1875
|
+
"ok": {
|
|
1876
|
+
"type": "boolean",
|
|
1877
|
+
"enum": [
|
|
1878
|
+
false
|
|
1879
|
+
],
|
|
1880
|
+
"description": "Present (false) on auth-gate rejections."
|
|
1881
|
+
},
|
|
1882
|
+
"error_kind": {
|
|
1883
|
+
"type": "string",
|
|
1884
|
+
"description": "Machine-readable failure class (rate_limit, validation, not_found, ...)."
|
|
1885
|
+
},
|
|
1886
|
+
"message": {
|
|
1887
|
+
"type": "string",
|
|
1888
|
+
"description": "Longer human-readable detail (feedback + some rate-limit errors)."
|
|
1889
|
+
},
|
|
1890
|
+
"rate": {
|
|
1891
|
+
"$ref": "#/components/schemas/RateInfo"
|
|
1892
|
+
},
|
|
1893
|
+
"retry_after_seconds": {
|
|
1894
|
+
"type": "integer",
|
|
1895
|
+
"description": "Seconds to wait before retrying (on 429)."
|
|
1896
|
+
},
|
|
1897
|
+
"tier": {
|
|
1898
|
+
"type": "string",
|
|
1899
|
+
"description": "The caller's current tier — present on a tier/scope authorization (403) rejection."
|
|
1900
|
+
},
|
|
1901
|
+
"current_tier": {
|
|
1902
|
+
"type": "string",
|
|
1903
|
+
"description": "The caller's current tier — present on a tier/request validation (400) rejection."
|
|
1904
|
+
},
|
|
1905
|
+
"detail": {
|
|
1906
|
+
"type": "string",
|
|
1907
|
+
"description": "Extra failure detail — present on some 500 responses (e.g. the agent event-log read)."
|
|
1908
|
+
}
|
|
1909
|
+
}
|
|
1910
|
+
},
|
|
1911
|
+
"RateInfo": {
|
|
1912
|
+
"type": "object",
|
|
1913
|
+
"description": "Per-token rate-limit snapshot returned by write endpoints.",
|
|
1914
|
+
"properties": {
|
|
1915
|
+
"current": {
|
|
1916
|
+
"type": "integer"
|
|
1917
|
+
},
|
|
1918
|
+
"remaining": {
|
|
1919
|
+
"type": "integer"
|
|
1920
|
+
},
|
|
1921
|
+
"limit": {
|
|
1922
|
+
"type": "integer"
|
|
1923
|
+
}
|
|
1924
|
+
}
|
|
1925
|
+
},
|
|
1926
|
+
"EventSummary": {
|
|
1927
|
+
"type": "object",
|
|
1928
|
+
"description": "One cached upcoming event. Passthrough of lib/events-ops shape; extra fields may appear.",
|
|
1929
|
+
"additionalProperties": true,
|
|
1930
|
+
"properties": {
|
|
1931
|
+
"luma_url": {
|
|
1932
|
+
"type": "string"
|
|
1933
|
+
},
|
|
1934
|
+
"title": {
|
|
1935
|
+
"type": "string"
|
|
1936
|
+
},
|
|
1937
|
+
"start": {
|
|
1938
|
+
"type": "string",
|
|
1939
|
+
"format": "date-time"
|
|
1940
|
+
},
|
|
1941
|
+
"end": {
|
|
1942
|
+
"type": "string",
|
|
1943
|
+
"format": "date-time"
|
|
1944
|
+
},
|
|
1945
|
+
"location": {
|
|
1946
|
+
"type": "string"
|
|
1947
|
+
},
|
|
1948
|
+
"cover_url": {
|
|
1949
|
+
"type": "string"
|
|
1950
|
+
}
|
|
1951
|
+
}
|
|
1952
|
+
},
|
|
1953
|
+
"UpcomingEventsResponse": {
|
|
1954
|
+
"type": "object",
|
|
1955
|
+
"required": [
|
|
1956
|
+
"ok"
|
|
1957
|
+
],
|
|
1958
|
+
"properties": {
|
|
1959
|
+
"ok": {
|
|
1960
|
+
"type": "boolean"
|
|
1961
|
+
},
|
|
1962
|
+
"events": {
|
|
1963
|
+
"type": "array",
|
|
1964
|
+
"items": {
|
|
1965
|
+
"$ref": "#/components/schemas/EventSummary"
|
|
1966
|
+
}
|
|
1967
|
+
},
|
|
1968
|
+
"count": {
|
|
1969
|
+
"type": "integer"
|
|
1970
|
+
},
|
|
1971
|
+
"age_min": {
|
|
1972
|
+
"type": "number",
|
|
1973
|
+
"description": "Minutes since the cache was last refreshed."
|
|
1974
|
+
}
|
|
1975
|
+
},
|
|
1976
|
+
"additionalProperties": true
|
|
1977
|
+
},
|
|
1978
|
+
"EventGetResponse": {
|
|
1979
|
+
"type": "object",
|
|
1980
|
+
"required": [
|
|
1981
|
+
"ok",
|
|
1982
|
+
"event"
|
|
1983
|
+
],
|
|
1984
|
+
"properties": {
|
|
1985
|
+
"ok": {
|
|
1986
|
+
"type": "boolean"
|
|
1987
|
+
},
|
|
1988
|
+
"event": {
|
|
1989
|
+
"$ref": "#/components/schemas/EventSummary"
|
|
1990
|
+
}
|
|
1991
|
+
}
|
|
1992
|
+
},
|
|
1993
|
+
"AgentEventsNextResponse": {
|
|
1994
|
+
"type": "object",
|
|
1995
|
+
"description": "Cursor-paginated page of agentic events.",
|
|
1996
|
+
"required": [
|
|
1997
|
+
"events"
|
|
1998
|
+
],
|
|
1999
|
+
"properties": {
|
|
2000
|
+
"events": {
|
|
2001
|
+
"type": "array",
|
|
2002
|
+
"items": {
|
|
2003
|
+
"type": "object",
|
|
2004
|
+
"additionalProperties": true
|
|
2005
|
+
}
|
|
2006
|
+
},
|
|
2007
|
+
"cursor": {
|
|
2008
|
+
"type": "integer",
|
|
2009
|
+
"description": "Pass as `since` to fetch the next page."
|
|
2010
|
+
},
|
|
2011
|
+
"has_more": {
|
|
2012
|
+
"type": "boolean",
|
|
2013
|
+
"description": "True when more events remain past this page."
|
|
2014
|
+
},
|
|
2015
|
+
"as_of": {
|
|
2016
|
+
"type": "string",
|
|
2017
|
+
"format": "date-time"
|
|
2018
|
+
}
|
|
2019
|
+
},
|
|
2020
|
+
"additionalProperties": true
|
|
2021
|
+
},
|
|
2022
|
+
"RsvpRequest": {
|
|
2023
|
+
"type": "object",
|
|
2024
|
+
"required": [
|
|
2025
|
+
"event_url"
|
|
2026
|
+
],
|
|
2027
|
+
"properties": {
|
|
2028
|
+
"event_url": {
|
|
2029
|
+
"type": "string",
|
|
2030
|
+
"description": "https://luma.com/<slug>"
|
|
2031
|
+
},
|
|
2032
|
+
"email": {
|
|
2033
|
+
"type": "string",
|
|
2034
|
+
"description": "Required for agent callers (no session fallback); optional on the Clerk path."
|
|
2035
|
+
},
|
|
2036
|
+
"name": {
|
|
2037
|
+
"type": "string"
|
|
2038
|
+
}
|
|
2039
|
+
}
|
|
2040
|
+
},
|
|
2041
|
+
"EventRequestRequest": {
|
|
2042
|
+
"type": "object",
|
|
2043
|
+
"required": [
|
|
2044
|
+
"title",
|
|
2045
|
+
"start"
|
|
2046
|
+
],
|
|
2047
|
+
"description": "Luma-shaped event proposal (EventRequestDetails).",
|
|
2048
|
+
"properties": {
|
|
2049
|
+
"title": {
|
|
2050
|
+
"type": "string"
|
|
2051
|
+
},
|
|
2052
|
+
"start": {
|
|
2053
|
+
"type": "string",
|
|
2054
|
+
"format": "date-time",
|
|
2055
|
+
"description": "Future ISO-8601 start."
|
|
2056
|
+
},
|
|
2057
|
+
"end": {
|
|
2058
|
+
"type": "string",
|
|
2059
|
+
"format": "date-time"
|
|
2060
|
+
},
|
|
2061
|
+
"location": {
|
|
2062
|
+
"type": "string"
|
|
2063
|
+
},
|
|
2064
|
+
"description": {
|
|
2065
|
+
"type": "string"
|
|
2066
|
+
},
|
|
2067
|
+
"cover_url": {
|
|
2068
|
+
"type": "string"
|
|
2069
|
+
},
|
|
2070
|
+
"capacity": {
|
|
2071
|
+
"type": "integer"
|
|
2072
|
+
},
|
|
2073
|
+
"visibility": {
|
|
2074
|
+
"type": "string",
|
|
2075
|
+
"enum": [
|
|
2076
|
+
"public",
|
|
2077
|
+
"members"
|
|
2078
|
+
]
|
|
2079
|
+
},
|
|
2080
|
+
"host": {
|
|
2081
|
+
"type": "string"
|
|
2082
|
+
},
|
|
2083
|
+
"contact": {
|
|
2084
|
+
"type": "string"
|
|
2085
|
+
},
|
|
2086
|
+
"slideshow_url": {
|
|
2087
|
+
"type": "string"
|
|
2088
|
+
}
|
|
2089
|
+
}
|
|
2090
|
+
},
|
|
2091
|
+
"EventRequestResponse": {
|
|
2092
|
+
"type": "object",
|
|
2093
|
+
"required": [
|
|
2094
|
+
"ok",
|
|
2095
|
+
"id",
|
|
2096
|
+
"status"
|
|
2097
|
+
],
|
|
2098
|
+
"properties": {
|
|
2099
|
+
"ok": {
|
|
2100
|
+
"type": "boolean"
|
|
2101
|
+
},
|
|
2102
|
+
"id": {
|
|
2103
|
+
"type": "string"
|
|
2104
|
+
},
|
|
2105
|
+
"status": {
|
|
2106
|
+
"type": "string",
|
|
2107
|
+
"enum": [
|
|
2108
|
+
"pending"
|
|
2109
|
+
]
|
|
2110
|
+
},
|
|
2111
|
+
"via": {
|
|
2112
|
+
"type": "string",
|
|
2113
|
+
"enum": [
|
|
2114
|
+
"clerk",
|
|
2115
|
+
"agent"
|
|
2116
|
+
]
|
|
2117
|
+
}
|
|
2118
|
+
}
|
|
2119
|
+
},
|
|
2120
|
+
"QueueResponse": {
|
|
2121
|
+
"type": "object",
|
|
2122
|
+
"description": "Shared shape for the queue-and-forget writes (rsvp, book).",
|
|
2123
|
+
"required": [
|
|
2124
|
+
"ok",
|
|
2125
|
+
"queued"
|
|
2126
|
+
],
|
|
2127
|
+
"properties": {
|
|
2128
|
+
"ok": {
|
|
2129
|
+
"type": "boolean"
|
|
2130
|
+
},
|
|
2131
|
+
"queued": {
|
|
2132
|
+
"type": "boolean"
|
|
2133
|
+
},
|
|
2134
|
+
"was_dup": {
|
|
2135
|
+
"type": "boolean",
|
|
2136
|
+
"description": "True when semantic dedupe recognized this as a repeat within the window."
|
|
2137
|
+
},
|
|
2138
|
+
"rate": {
|
|
2139
|
+
"$ref": "#/components/schemas/RateInfo"
|
|
2140
|
+
},
|
|
2141
|
+
"via": {
|
|
2142
|
+
"type": "string",
|
|
2143
|
+
"enum": [
|
|
2144
|
+
"clerk",
|
|
2145
|
+
"agent"
|
|
2146
|
+
]
|
|
2147
|
+
},
|
|
2148
|
+
"note": {
|
|
2149
|
+
"type": "string"
|
|
2150
|
+
}
|
|
2151
|
+
}
|
|
2152
|
+
},
|
|
2153
|
+
"BatchSubRequest": {
|
|
2154
|
+
"type": "object",
|
|
2155
|
+
"required": [
|
|
2156
|
+
"path"
|
|
2157
|
+
],
|
|
2158
|
+
"description": "One GET sub-request in a batch.",
|
|
2159
|
+
"properties": {
|
|
2160
|
+
"id": {
|
|
2161
|
+
"type": "string",
|
|
2162
|
+
"description": "Optional caller correlation id; echoed back verbatim on the matching result."
|
|
2163
|
+
},
|
|
2164
|
+
"method": {
|
|
2165
|
+
"type": "string",
|
|
2166
|
+
"enum": [
|
|
2167
|
+
"GET"
|
|
2168
|
+
],
|
|
2169
|
+
"default": "GET",
|
|
2170
|
+
"description": "Only GET sub-requests are batchable."
|
|
2171
|
+
},
|
|
2172
|
+
"path": {
|
|
2173
|
+
"type": "string",
|
|
2174
|
+
"description": "An allowlisted public /api path, optionally with a query string (e.g. /api/events/upcoming?limit=3). Allowed: /api/events/upcoming, /api/events/get, /api/floor10/donations."
|
|
2175
|
+
}
|
|
2176
|
+
}
|
|
2177
|
+
},
|
|
2178
|
+
"BatchRequest": {
|
|
2179
|
+
"type": "object",
|
|
2180
|
+
"required": [
|
|
2181
|
+
"requests"
|
|
2182
|
+
],
|
|
2183
|
+
"description": "A bounded list (1..20) of public GET sub-requests to run in one round-trip.",
|
|
2184
|
+
"properties": {
|
|
2185
|
+
"requests": {
|
|
2186
|
+
"type": "array",
|
|
2187
|
+
"minItems": 1,
|
|
2188
|
+
"maxItems": 20,
|
|
2189
|
+
"items": {
|
|
2190
|
+
"$ref": "#/components/schemas/BatchSubRequest"
|
|
2191
|
+
}
|
|
2192
|
+
}
|
|
2193
|
+
}
|
|
2194
|
+
},
|
|
2195
|
+
"BatchResultItem": {
|
|
2196
|
+
"type": "object",
|
|
2197
|
+
"required": [
|
|
2198
|
+
"path",
|
|
2199
|
+
"status",
|
|
2200
|
+
"ok",
|
|
2201
|
+
"body"
|
|
2202
|
+
],
|
|
2203
|
+
"description": "One sub-request's outcome. `status`/`ok`/`body` are exactly what the target endpoint would have returned; a rejected sub-request (non-allowlisted path, non-GET, or handler error) carries a 4xx/5xx status + an { error } body while the batch envelope stays 200.",
|
|
2204
|
+
"additionalProperties": true,
|
|
2205
|
+
"properties": {
|
|
2206
|
+
"id": {
|
|
2207
|
+
"type": "string",
|
|
2208
|
+
"description": "Echoed from the sub-request if one was supplied."
|
|
2209
|
+
},
|
|
2210
|
+
"path": {
|
|
2211
|
+
"type": "string",
|
|
2212
|
+
"description": "The sub-request path as sent."
|
|
2213
|
+
},
|
|
2214
|
+
"status": {
|
|
2215
|
+
"type": "integer",
|
|
2216
|
+
"description": "HTTP status the target handler returned (or a 4xx/5xx synthesized for a rejected sub-request)."
|
|
2217
|
+
},
|
|
2218
|
+
"ok": {
|
|
2219
|
+
"type": "boolean",
|
|
2220
|
+
"description": "True iff status is 2xx."
|
|
2221
|
+
},
|
|
2222
|
+
"body": {
|
|
2223
|
+
"type": "object",
|
|
2224
|
+
"additionalProperties": true,
|
|
2225
|
+
"description": "The target endpoint's JSON body (or an { error } object on a rejected sub-request)."
|
|
2226
|
+
}
|
|
2227
|
+
}
|
|
2228
|
+
},
|
|
2229
|
+
"BatchResponse": {
|
|
2230
|
+
"type": "object",
|
|
2231
|
+
"required": [
|
|
2232
|
+
"ok",
|
|
2233
|
+
"count",
|
|
2234
|
+
"results"
|
|
2235
|
+
],
|
|
2236
|
+
"properties": {
|
|
2237
|
+
"ok": {
|
|
2238
|
+
"type": "boolean"
|
|
2239
|
+
},
|
|
2240
|
+
"count": {
|
|
2241
|
+
"type": "integer",
|
|
2242
|
+
"description": "Number of results (equals requests.length)."
|
|
2243
|
+
},
|
|
2244
|
+
"results": {
|
|
2245
|
+
"type": "array",
|
|
2246
|
+
"items": {
|
|
2247
|
+
"$ref": "#/components/schemas/BatchResultItem"
|
|
2248
|
+
}
|
|
2249
|
+
}
|
|
2250
|
+
}
|
|
2251
|
+
},
|
|
2252
|
+
"DirectorySearchResponse": {
|
|
2253
|
+
"type": "object",
|
|
2254
|
+
"description": "Privacy-graded results; the fields per member depend on the caller's tier.",
|
|
2255
|
+
"properties": {
|
|
2256
|
+
"results": {
|
|
2257
|
+
"type": "array",
|
|
2258
|
+
"items": {
|
|
2259
|
+
"type": "object",
|
|
2260
|
+
"additionalProperties": true
|
|
2261
|
+
}
|
|
2262
|
+
},
|
|
2263
|
+
"count": {
|
|
2264
|
+
"type": "integer"
|
|
2265
|
+
},
|
|
2266
|
+
"query": {
|
|
2267
|
+
"type": "string"
|
|
2268
|
+
}
|
|
2269
|
+
},
|
|
2270
|
+
"additionalProperties": true
|
|
2271
|
+
},
|
|
2272
|
+
"ResourcesListResponse": {
|
|
2273
|
+
"type": "object",
|
|
2274
|
+
"required": [
|
|
2275
|
+
"ok"
|
|
2276
|
+
],
|
|
2277
|
+
"properties": {
|
|
2278
|
+
"ok": {
|
|
2279
|
+
"type": "boolean"
|
|
2280
|
+
},
|
|
2281
|
+
"resources": {
|
|
2282
|
+
"type": "array",
|
|
2283
|
+
"items": {
|
|
2284
|
+
"type": "object",
|
|
2285
|
+
"additionalProperties": true
|
|
2286
|
+
}
|
|
2287
|
+
},
|
|
2288
|
+
"via": {
|
|
2289
|
+
"type": "string",
|
|
2290
|
+
"enum": [
|
|
2291
|
+
"clerk",
|
|
2292
|
+
"agent"
|
|
2293
|
+
]
|
|
2294
|
+
}
|
|
2295
|
+
},
|
|
2296
|
+
"additionalProperties": true
|
|
2297
|
+
},
|
|
2298
|
+
"BookRequest": {
|
|
2299
|
+
"type": "object",
|
|
2300
|
+
"required": [
|
|
2301
|
+
"resource_id",
|
|
2302
|
+
"start_iso",
|
|
2303
|
+
"end_iso"
|
|
2304
|
+
],
|
|
2305
|
+
"properties": {
|
|
2306
|
+
"resource_id": {
|
|
2307
|
+
"type": "string",
|
|
2308
|
+
"description": "e.g. \"ft-9\" or \"printer-prusa-1\"."
|
|
2309
|
+
},
|
|
2310
|
+
"start_iso": {
|
|
2311
|
+
"type": "string",
|
|
2312
|
+
"format": "date-time"
|
|
2313
|
+
},
|
|
2314
|
+
"end_iso": {
|
|
2315
|
+
"type": "string",
|
|
2316
|
+
"format": "date-time",
|
|
2317
|
+
"description": "After start."
|
|
2318
|
+
},
|
|
2319
|
+
"purpose": {
|
|
2320
|
+
"type": "string",
|
|
2321
|
+
"description": "Free text, trimmed + clipped to 600 chars server-side."
|
|
2322
|
+
},
|
|
2323
|
+
"email": {
|
|
2324
|
+
"type": "string",
|
|
2325
|
+
"description": "Required for agent callers; optional on the Clerk path."
|
|
2326
|
+
}
|
|
2327
|
+
}
|
|
2328
|
+
},
|
|
2329
|
+
"ActivityResponse": {
|
|
2330
|
+
"type": "object",
|
|
2331
|
+
"required": [
|
|
2332
|
+
"ok",
|
|
2333
|
+
"events"
|
|
2334
|
+
],
|
|
2335
|
+
"properties": {
|
|
2336
|
+
"ok": {
|
|
2337
|
+
"type": "boolean"
|
|
2338
|
+
},
|
|
2339
|
+
"count": {
|
|
2340
|
+
"type": "integer"
|
|
2341
|
+
},
|
|
2342
|
+
"limit": {
|
|
2343
|
+
"type": "integer"
|
|
2344
|
+
},
|
|
2345
|
+
"events": {
|
|
2346
|
+
"type": "array",
|
|
2347
|
+
"items": {
|
|
2348
|
+
"type": "object",
|
|
2349
|
+
"additionalProperties": true
|
|
2350
|
+
}
|
|
2351
|
+
},
|
|
2352
|
+
"via": {
|
|
2353
|
+
"type": "string",
|
|
2354
|
+
"enum": [
|
|
2355
|
+
"clerk",
|
|
2356
|
+
"agent"
|
|
2357
|
+
]
|
|
2358
|
+
}
|
|
2359
|
+
}
|
|
2360
|
+
},
|
|
2361
|
+
"LeaderboardMeResponse": {
|
|
2362
|
+
"type": "object",
|
|
2363
|
+
"required": [
|
|
2364
|
+
"ok"
|
|
2365
|
+
],
|
|
2366
|
+
"properties": {
|
|
2367
|
+
"ok": {
|
|
2368
|
+
"type": "boolean"
|
|
2369
|
+
},
|
|
2370
|
+
"optIn": {
|
|
2371
|
+
"type": "boolean"
|
|
2372
|
+
},
|
|
2373
|
+
"github_username": {
|
|
2374
|
+
"type": "string"
|
|
2375
|
+
},
|
|
2376
|
+
"github_link_source": {
|
|
2377
|
+
"type": "string",
|
|
2378
|
+
"enum": [
|
|
2379
|
+
"oauth",
|
|
2380
|
+
"agent_pat"
|
|
2381
|
+
]
|
|
2382
|
+
},
|
|
2383
|
+
"github_verified_at": {
|
|
2384
|
+
"type": "string",
|
|
2385
|
+
"format": "date-time"
|
|
2386
|
+
},
|
|
2387
|
+
"this_week": {
|
|
2388
|
+
"type": "object",
|
|
2389
|
+
"properties": {
|
|
2390
|
+
"count": {
|
|
2391
|
+
"type": "integer"
|
|
2392
|
+
},
|
|
2393
|
+
"rank": {
|
|
2394
|
+
"type": "integer"
|
|
2395
|
+
},
|
|
2396
|
+
"total": {
|
|
2397
|
+
"type": "integer"
|
|
2398
|
+
},
|
|
2399
|
+
"generated_at": {
|
|
2400
|
+
"type": "string",
|
|
2401
|
+
"format": "date-time"
|
|
2402
|
+
}
|
|
2403
|
+
}
|
|
2404
|
+
}
|
|
2405
|
+
},
|
|
2406
|
+
"additionalProperties": true
|
|
2407
|
+
},
|
|
2408
|
+
"LeaderboardOptInRequest": {
|
|
2409
|
+
"type": "object",
|
|
2410
|
+
"required": [
|
|
2411
|
+
"optIn"
|
|
2412
|
+
],
|
|
2413
|
+
"properties": {
|
|
2414
|
+
"optIn": {
|
|
2415
|
+
"type": "boolean"
|
|
2416
|
+
}
|
|
2417
|
+
}
|
|
2418
|
+
},
|
|
2419
|
+
"LeaderboardOptInResponse": {
|
|
2420
|
+
"type": "object",
|
|
2421
|
+
"required": [
|
|
2422
|
+
"ok",
|
|
2423
|
+
"optIn"
|
|
2424
|
+
],
|
|
2425
|
+
"properties": {
|
|
2426
|
+
"ok": {
|
|
2427
|
+
"type": "boolean"
|
|
2428
|
+
},
|
|
2429
|
+
"optIn": {
|
|
2430
|
+
"type": "boolean"
|
|
2431
|
+
},
|
|
2432
|
+
"github_username": {
|
|
2433
|
+
"type": "string"
|
|
2434
|
+
},
|
|
2435
|
+
"via": {
|
|
2436
|
+
"type": "string",
|
|
2437
|
+
"enum": [
|
|
2438
|
+
"clerk",
|
|
2439
|
+
"agent"
|
|
2440
|
+
]
|
|
2441
|
+
}
|
|
2442
|
+
}
|
|
2443
|
+
},
|
|
2444
|
+
"ResearchAskRequest": {
|
|
2445
|
+
"type": "object",
|
|
2446
|
+
"required": [
|
|
2447
|
+
"q"
|
|
2448
|
+
],
|
|
2449
|
+
"properties": {
|
|
2450
|
+
"q": {
|
|
2451
|
+
"type": "string",
|
|
2452
|
+
"maxLength": 500,
|
|
2453
|
+
"description": "The query."
|
|
2454
|
+
},
|
|
2455
|
+
"k": {
|
|
2456
|
+
"type": "integer",
|
|
2457
|
+
"minimum": 1,
|
|
2458
|
+
"maximum": 50,
|
|
2459
|
+
"default": 10
|
|
2460
|
+
},
|
|
2461
|
+
"sources": {
|
|
2462
|
+
"type": "array",
|
|
2463
|
+
"items": {
|
|
2464
|
+
"type": "string",
|
|
2465
|
+
"enum": [
|
|
2466
|
+
"paper",
|
|
2467
|
+
"book"
|
|
2468
|
+
]
|
|
2469
|
+
},
|
|
2470
|
+
"default": [
|
|
2471
|
+
"paper"
|
|
2472
|
+
]
|
|
2473
|
+
},
|
|
2474
|
+
"synthesize": {
|
|
2475
|
+
"type": "boolean",
|
|
2476
|
+
"default": false,
|
|
2477
|
+
"description": "When true, returns an LLM-synthesized grounded answer."
|
|
2478
|
+
},
|
|
2479
|
+
"model": {
|
|
2480
|
+
"type": "string",
|
|
2481
|
+
"enum": [
|
|
2482
|
+
"claude-haiku-4-5",
|
|
2483
|
+
"claude-sonnet-4-6",
|
|
2484
|
+
"claude-opus-4-7"
|
|
2485
|
+
],
|
|
2486
|
+
"description": "Only valid when synthesize=true."
|
|
2487
|
+
}
|
|
2488
|
+
}
|
|
2489
|
+
},
|
|
2490
|
+
"ResearchAskResponse": {
|
|
2491
|
+
"type": "object",
|
|
2492
|
+
"description": "Passthrough from the RAG funnel. `/search` returns { results, via }; `/synthesize` returns { q, k, model, answer, citations, retrieval_results, usage, via }.",
|
|
2493
|
+
"additionalProperties": true,
|
|
2494
|
+
"properties": {
|
|
2495
|
+
"results": {
|
|
2496
|
+
"type": "array",
|
|
2497
|
+
"items": {
|
|
2498
|
+
"type": "object",
|
|
2499
|
+
"additionalProperties": true
|
|
2500
|
+
}
|
|
2501
|
+
},
|
|
2502
|
+
"answer": {
|
|
2503
|
+
"type": "string"
|
|
2504
|
+
},
|
|
2505
|
+
"citations": {
|
|
2506
|
+
"type": "array",
|
|
2507
|
+
"items": {
|
|
2508
|
+
"type": "object",
|
|
2509
|
+
"additionalProperties": true
|
|
2510
|
+
}
|
|
2511
|
+
},
|
|
2512
|
+
"via": {
|
|
2513
|
+
"type": "string"
|
|
2514
|
+
}
|
|
2515
|
+
}
|
|
2516
|
+
},
|
|
2517
|
+
"HighlightPendingRequest": {
|
|
2518
|
+
"type": "object",
|
|
2519
|
+
"description": "A HighlightStory, or an object wrapping one under `story`. Validated by lib/highlights-pending.ts.",
|
|
2520
|
+
"additionalProperties": true,
|
|
2521
|
+
"properties": {
|
|
2522
|
+
"id": {
|
|
2523
|
+
"type": "string",
|
|
2524
|
+
"description": "Stable id — re-submitting the same id refreshes the pending record (dedupe)."
|
|
2525
|
+
},
|
|
2526
|
+
"story": {
|
|
2527
|
+
"type": "object",
|
|
2528
|
+
"additionalProperties": true,
|
|
2529
|
+
"description": "Optional wrapper; the story fields may also be sent at the top level."
|
|
2530
|
+
}
|
|
2531
|
+
}
|
|
2532
|
+
},
|
|
2533
|
+
"HighlightPendingResponse": {
|
|
2534
|
+
"type": "object",
|
|
2535
|
+
"required": [
|
|
2536
|
+
"ok",
|
|
2537
|
+
"id",
|
|
2538
|
+
"status"
|
|
2539
|
+
],
|
|
2540
|
+
"properties": {
|
|
2541
|
+
"ok": {
|
|
2542
|
+
"type": "boolean"
|
|
2543
|
+
},
|
|
2544
|
+
"id": {
|
|
2545
|
+
"type": "string"
|
|
2546
|
+
},
|
|
2547
|
+
"job_id": {
|
|
2548
|
+
"type": "string",
|
|
2549
|
+
"description": "Async-job handle (= `id`) to poll this submission with. Mirrors the `Location` header + `poll_url`."
|
|
2550
|
+
},
|
|
2551
|
+
"status": {
|
|
2552
|
+
"type": "string",
|
|
2553
|
+
"enum": [
|
|
2554
|
+
"pending"
|
|
2555
|
+
]
|
|
2556
|
+
},
|
|
2557
|
+
"poll_url": {
|
|
2558
|
+
"type": "string",
|
|
2559
|
+
"description": "Status-poll URL: GET /api/ingest/highlights/pending?id=<job_id> → { status: pending | gone }. Same URL as the `Location` response header."
|
|
2560
|
+
},
|
|
2561
|
+
"rate": {
|
|
2562
|
+
"$ref": "#/components/schemas/RateInfo"
|
|
2563
|
+
},
|
|
2564
|
+
"expires_at": {
|
|
2565
|
+
"type": "string",
|
|
2566
|
+
"format": "date-time"
|
|
2567
|
+
}
|
|
2568
|
+
}
|
|
2569
|
+
},
|
|
2570
|
+
"FeedbackSubmitRequest": {
|
|
2571
|
+
"type": "object",
|
|
2572
|
+
"required": [
|
|
2573
|
+
"kind",
|
|
2574
|
+
"message"
|
|
2575
|
+
],
|
|
2576
|
+
"properties": {
|
|
2577
|
+
"kind": {
|
|
2578
|
+
"type": "string",
|
|
2579
|
+
"enum": [
|
|
2580
|
+
"broken_url",
|
|
2581
|
+
"schema_mismatch",
|
|
2582
|
+
"stale_doc",
|
|
2583
|
+
"endpoint_404",
|
|
2584
|
+
"bug_report",
|
|
2585
|
+
"other",
|
|
2586
|
+
"feature_request",
|
|
2587
|
+
"praise",
|
|
2588
|
+
"complaint",
|
|
2589
|
+
"question",
|
|
2590
|
+
"suggestion"
|
|
2591
|
+
]
|
|
2592
|
+
},
|
|
2593
|
+
"message": {
|
|
2594
|
+
"type": "string",
|
|
2595
|
+
"maxLength": 2000
|
|
2596
|
+
},
|
|
2597
|
+
"url": {
|
|
2598
|
+
"type": "string",
|
|
2599
|
+
"maxLength": 500
|
|
2600
|
+
},
|
|
2601
|
+
"expected": {
|
|
2602
|
+
"type": "string",
|
|
2603
|
+
"maxLength": 500
|
|
2604
|
+
},
|
|
2605
|
+
"got": {
|
|
2606
|
+
"type": "string",
|
|
2607
|
+
"maxLength": 500
|
|
2608
|
+
},
|
|
2609
|
+
"priority": {
|
|
2610
|
+
"type": "string",
|
|
2611
|
+
"enum": [
|
|
2612
|
+
"low",
|
|
2613
|
+
"normal",
|
|
2614
|
+
"high"
|
|
2615
|
+
]
|
|
2616
|
+
},
|
|
2617
|
+
"category": {
|
|
2618
|
+
"type": "string",
|
|
2619
|
+
"maxLength": 500
|
|
2620
|
+
},
|
|
2621
|
+
"agent_id": {
|
|
2622
|
+
"type": "string",
|
|
2623
|
+
"maxLength": 500
|
|
2624
|
+
},
|
|
2625
|
+
"contact": {
|
|
2626
|
+
"type": "string",
|
|
2627
|
+
"maxLength": 500
|
|
2628
|
+
}
|
|
2629
|
+
}
|
|
2630
|
+
},
|
|
2631
|
+
"FeedbackSubmitResponse": {
|
|
2632
|
+
"type": "object",
|
|
2633
|
+
"required": [
|
|
2634
|
+
"ok",
|
|
2635
|
+
"ticket_id"
|
|
2636
|
+
],
|
|
2637
|
+
"properties": {
|
|
2638
|
+
"ok": {
|
|
2639
|
+
"type": "boolean"
|
|
2640
|
+
},
|
|
2641
|
+
"ticket_id": {
|
|
2642
|
+
"type": "string",
|
|
2643
|
+
"description": "Quote this when following up."
|
|
2644
|
+
},
|
|
2645
|
+
"received_at": {
|
|
2646
|
+
"type": "string",
|
|
2647
|
+
"format": "date-time"
|
|
2648
|
+
},
|
|
2649
|
+
"authenticated": {
|
|
2650
|
+
"type": "boolean",
|
|
2651
|
+
"description": "True iff a valid Bearer attributed the submission."
|
|
2652
|
+
},
|
|
2653
|
+
"message": {
|
|
2654
|
+
"type": "string"
|
|
2655
|
+
},
|
|
2656
|
+
"warnings": {
|
|
2657
|
+
"type": "array",
|
|
2658
|
+
"items": {
|
|
2659
|
+
"type": "string"
|
|
2660
|
+
}
|
|
2661
|
+
}
|
|
2662
|
+
}
|
|
2663
|
+
},
|
|
2664
|
+
"TokenRevokeResponse": {
|
|
2665
|
+
"type": "object",
|
|
2666
|
+
"required": [
|
|
2667
|
+
"ok",
|
|
2668
|
+
"revoked"
|
|
2669
|
+
],
|
|
2670
|
+
"properties": {
|
|
2671
|
+
"ok": {
|
|
2672
|
+
"type": "boolean"
|
|
2673
|
+
},
|
|
2674
|
+
"revoked": {
|
|
2675
|
+
"type": "boolean"
|
|
2676
|
+
},
|
|
2677
|
+
"prefix": {
|
|
2678
|
+
"type": "string"
|
|
2679
|
+
},
|
|
2680
|
+
"already_revoked": {
|
|
2681
|
+
"type": "boolean"
|
|
2682
|
+
}
|
|
2683
|
+
}
|
|
2684
|
+
},
|
|
2685
|
+
"SetupCheckResponse": {
|
|
2686
|
+
"type": "object",
|
|
2687
|
+
"required": [
|
|
2688
|
+
"ready"
|
|
2689
|
+
],
|
|
2690
|
+
"description": "ready:true carries checks{scopes,member_id,...}+mcp; ready:false carries missing[]+next_actions[]+mcp.",
|
|
2691
|
+
"additionalProperties": true,
|
|
2692
|
+
"properties": {
|
|
2693
|
+
"ready": {
|
|
2694
|
+
"type": "boolean"
|
|
2695
|
+
},
|
|
2696
|
+
"checks": {
|
|
2697
|
+
"type": "object",
|
|
2698
|
+
"additionalProperties": true
|
|
2699
|
+
},
|
|
2700
|
+
"missing": {
|
|
2701
|
+
"type": "array",
|
|
2702
|
+
"items": {
|
|
2703
|
+
"type": "string"
|
|
2704
|
+
}
|
|
2705
|
+
},
|
|
2706
|
+
"next_actions": {
|
|
2707
|
+
"type": "array",
|
|
2708
|
+
"items": {
|
|
2709
|
+
"type": "object",
|
|
2710
|
+
"additionalProperties": true
|
|
2711
|
+
}
|
|
2712
|
+
},
|
|
2713
|
+
"mcp": {
|
|
2714
|
+
"type": "object",
|
|
2715
|
+
"additionalProperties": true
|
|
2716
|
+
}
|
|
2717
|
+
}
|
|
2718
|
+
},
|
|
2719
|
+
"SignupStartRequest": {
|
|
2720
|
+
"type": "object",
|
|
2721
|
+
"required": [
|
|
2722
|
+
"scopes"
|
|
2723
|
+
],
|
|
2724
|
+
"properties": {
|
|
2725
|
+
"scopes": {
|
|
2726
|
+
"type": "array",
|
|
2727
|
+
"items": {
|
|
2728
|
+
"type": "string"
|
|
2729
|
+
},
|
|
2730
|
+
"minItems": 1,
|
|
2731
|
+
"maxItems": 64,
|
|
2732
|
+
"description": "Requested capability scopes (validated against the user's tier at approval)."
|
|
2733
|
+
},
|
|
2734
|
+
"client_name": {
|
|
2735
|
+
"type": "string",
|
|
2736
|
+
"maxLength": 80,
|
|
2737
|
+
"description": "Free-text agent identifier shown to the approving human."
|
|
2738
|
+
},
|
|
2739
|
+
"sandbox": {
|
|
2740
|
+
"type": "boolean",
|
|
2741
|
+
"description": "Mint a sandbox/test-mode token: WRITE verbs return a simulated receipt instead of mutating; reads serve real data. Still a real token with real scopes — this does NOT widen access. Immutable after mint. See the root x-sandbox extension."
|
|
2742
|
+
}
|
|
2743
|
+
}
|
|
2744
|
+
},
|
|
2745
|
+
"SignupStartResponse": {
|
|
2746
|
+
"type": "object",
|
|
2747
|
+
"required": [
|
|
2748
|
+
"device_code",
|
|
2749
|
+
"user_code",
|
|
2750
|
+
"verify_url",
|
|
2751
|
+
"expires_in",
|
|
2752
|
+
"interval"
|
|
2753
|
+
],
|
|
2754
|
+
"properties": {
|
|
2755
|
+
"device_code": {
|
|
2756
|
+
"type": "string",
|
|
2757
|
+
"description": "Long secret — the agent keeps it, never displays it."
|
|
2758
|
+
},
|
|
2759
|
+
"user_code": {
|
|
2760
|
+
"type": "string",
|
|
2761
|
+
"description": "Short human-readable code."
|
|
2762
|
+
},
|
|
2763
|
+
"verify_url": {
|
|
2764
|
+
"type": "string"
|
|
2765
|
+
},
|
|
2766
|
+
"verify_url_complete": {
|
|
2767
|
+
"type": "string",
|
|
2768
|
+
"description": "verify_url + ?code= prefilled."
|
|
2769
|
+
},
|
|
2770
|
+
"expires_in": {
|
|
2771
|
+
"type": "integer",
|
|
2772
|
+
"description": "Seconds (900)."
|
|
2773
|
+
},
|
|
2774
|
+
"interval": {
|
|
2775
|
+
"type": "integer",
|
|
2776
|
+
"description": "Recommended poll interval in seconds (5)."
|
|
2777
|
+
}
|
|
2778
|
+
}
|
|
2779
|
+
},
|
|
2780
|
+
"SignupPollResponse": {
|
|
2781
|
+
"type": "object",
|
|
2782
|
+
"required": [
|
|
2783
|
+
"status"
|
|
2784
|
+
],
|
|
2785
|
+
"description": "One of pending / completed / cancelled. `completed` surfaces the agent_token exactly once.",
|
|
2786
|
+
"additionalProperties": true,
|
|
2787
|
+
"properties": {
|
|
2788
|
+
"status": {
|
|
2789
|
+
"type": "string",
|
|
2790
|
+
"enum": [
|
|
2791
|
+
"pending",
|
|
2792
|
+
"completed",
|
|
2793
|
+
"cancelled"
|
|
2794
|
+
]
|
|
2795
|
+
},
|
|
2796
|
+
"user_id": {
|
|
2797
|
+
"type": "string"
|
|
2798
|
+
},
|
|
2799
|
+
"agent_token": {
|
|
2800
|
+
"type": "string",
|
|
2801
|
+
"description": "Plaintext, surfaced ONCE — store it on the agent."
|
|
2802
|
+
},
|
|
2803
|
+
"tier": {
|
|
2804
|
+
"type": "string"
|
|
2805
|
+
},
|
|
2806
|
+
"pending_tier": {
|
|
2807
|
+
"type": "string"
|
|
2808
|
+
},
|
|
2809
|
+
"granted_scopes": {
|
|
2810
|
+
"type": "array",
|
|
2811
|
+
"items": {
|
|
2812
|
+
"type": "string"
|
|
2813
|
+
}
|
|
2814
|
+
},
|
|
2815
|
+
"sandbox": {
|
|
2816
|
+
"type": "boolean",
|
|
2817
|
+
"description": "Present + true when the minted token is a sandbox/test-mode token (mirrors the `sandbox` flag sent to /start)."
|
|
2818
|
+
},
|
|
2819
|
+
"reason": {
|
|
2820
|
+
"type": "string",
|
|
2821
|
+
"description": "On cancellation."
|
|
2822
|
+
},
|
|
2823
|
+
"next_steps": {
|
|
2824
|
+
"type": "object",
|
|
2825
|
+
"additionalProperties": true
|
|
2826
|
+
}
|
|
2827
|
+
}
|
|
2828
|
+
},
|
|
2829
|
+
"DonationsResponse": {
|
|
2830
|
+
"type": "object",
|
|
2831
|
+
"required": [
|
|
2832
|
+
"ok"
|
|
2833
|
+
],
|
|
2834
|
+
"properties": {
|
|
2835
|
+
"ok": {
|
|
2836
|
+
"type": "boolean"
|
|
2837
|
+
},
|
|
2838
|
+
"total_usdc": {
|
|
2839
|
+
"type": "number"
|
|
2840
|
+
},
|
|
2841
|
+
"donor_count": {
|
|
2842
|
+
"type": "integer"
|
|
2843
|
+
},
|
|
2844
|
+
"recent": {
|
|
2845
|
+
"type": "array",
|
|
2846
|
+
"items": {
|
|
2847
|
+
"type": "object",
|
|
2848
|
+
"additionalProperties": true
|
|
2849
|
+
}
|
|
2850
|
+
}
|
|
2851
|
+
},
|
|
2852
|
+
"additionalProperties": true
|
|
2853
|
+
},
|
|
2854
|
+
"TierMeResponse": {
|
|
2855
|
+
"type": "object",
|
|
2856
|
+
"required": [
|
|
2857
|
+
"ok",
|
|
2858
|
+
"tier"
|
|
2859
|
+
],
|
|
2860
|
+
"properties": {
|
|
2861
|
+
"ok": {
|
|
2862
|
+
"type": "boolean"
|
|
2863
|
+
},
|
|
2864
|
+
"tier": {
|
|
2865
|
+
"type": "string",
|
|
2866
|
+
"description": "public | ft-member | ai-floor | ic-member | operator"
|
|
2867
|
+
},
|
|
2868
|
+
"pending": {
|
|
2869
|
+
"type": [
|
|
2870
|
+
"object",
|
|
2871
|
+
"null"
|
|
2872
|
+
],
|
|
2873
|
+
"additionalProperties": true,
|
|
2874
|
+
"description": "The pending tier request, or null."
|
|
2875
|
+
},
|
|
2876
|
+
"history": {
|
|
2877
|
+
"type": "array",
|
|
2878
|
+
"items": {
|
|
2879
|
+
"type": "object",
|
|
2880
|
+
"additionalProperties": true
|
|
2881
|
+
}
|
|
2882
|
+
},
|
|
2883
|
+
"email": {
|
|
2884
|
+
"type": "string"
|
|
2885
|
+
},
|
|
2886
|
+
"display_name": {
|
|
2887
|
+
"type": "string"
|
|
2888
|
+
}
|
|
2889
|
+
}
|
|
2890
|
+
},
|
|
2891
|
+
"TierRequestRequest": {
|
|
2892
|
+
"type": "object",
|
|
2893
|
+
"required": [
|
|
2894
|
+
"tier"
|
|
2895
|
+
],
|
|
2896
|
+
"properties": {
|
|
2897
|
+
"tier": {
|
|
2898
|
+
"type": "string",
|
|
2899
|
+
"description": "A self-requestable tier ABOVE the caller's current tier."
|
|
2900
|
+
},
|
|
2901
|
+
"note": {
|
|
2902
|
+
"type": "string",
|
|
2903
|
+
"maxLength": 600
|
|
2904
|
+
}
|
|
2905
|
+
}
|
|
2906
|
+
},
|
|
2907
|
+
"TierRequestResponse": {
|
|
2908
|
+
"type": "object",
|
|
2909
|
+
"required": [
|
|
2910
|
+
"ok",
|
|
2911
|
+
"current_tier",
|
|
2912
|
+
"requested_tier"
|
|
2913
|
+
],
|
|
2914
|
+
"properties": {
|
|
2915
|
+
"ok": {
|
|
2916
|
+
"type": "boolean"
|
|
2917
|
+
},
|
|
2918
|
+
"current_tier": {
|
|
2919
|
+
"type": "string"
|
|
2920
|
+
},
|
|
2921
|
+
"requested_tier": {
|
|
2922
|
+
"type": "string"
|
|
2923
|
+
},
|
|
2924
|
+
"submitted_at": {
|
|
2925
|
+
"type": "string",
|
|
2926
|
+
"format": "date-time"
|
|
2927
|
+
},
|
|
2928
|
+
"kv_warning": {
|
|
2929
|
+
"type": "string",
|
|
2930
|
+
"description": "Present if the KV pending-queue write soft-failed (the request is still recorded)."
|
|
2931
|
+
}
|
|
2932
|
+
}
|
|
2933
|
+
},
|
|
2934
|
+
"TierRequestCancelResponse": {
|
|
2935
|
+
"type": "object",
|
|
2936
|
+
"required": [
|
|
2937
|
+
"ok",
|
|
2938
|
+
"was_pending"
|
|
2939
|
+
],
|
|
2940
|
+
"properties": {
|
|
2941
|
+
"ok": {
|
|
2942
|
+
"type": "boolean"
|
|
2943
|
+
},
|
|
2944
|
+
"was_pending": {
|
|
2945
|
+
"type": "boolean"
|
|
2946
|
+
}
|
|
2947
|
+
}
|
|
2948
|
+
}
|
|
2949
|
+
}
|
|
2950
|
+
}
|
|
2951
|
+
}
|