aaronrene / knowtation public
openapi.yaml yaml
3,778 lines 117.0 KB
Raw
sha256:c2dbf04d56308f3bbf2d06e6d2eb022b8948b1e827195fe525a44e5e18d5f9c0 feat(auth): Phase B Connect cloud agent (RFC 8628) + Hermes… Human minor ⚠ breaking 10 days ago
1 openapi: 3.0.3
2 info:
3 title: Knowtation Hub API
4 description: REST API for the Knowtation Hub (vault read/write, proposals, capture). Same contract as CLI/MCP where applicable.
5 version: 1.0.0
6 links:
7 - description: API contract (human-readable)
8 url: ./HUB-API.md
9
10 servers:
11 - url: /api/v1
12 description: Relative to Hub base URL (e.g. https://hub.example.com)
13
14 tags:
15 - name: Health
16 - name: Auth
17 - name: Notes
18 - name: Search
19 - name: Proposals
20 - name: Capture
21 - name: Flows
22 - name: Tasks
23 - name: Attachments
24
25 security:
26 - BearerAuth: []
27
28 paths:
29 /health:
30 get:
31 tags: [Health]
32 summary: Health check
33 security: []
34 responses:
35 '200':
36 description: Hub is up
37 content:
38 application/json:
39 schema: { type: object, properties: { ok: { type: boolean } }, required: [ok] }
40
41 /api/v1/auth/session:
42 get:
43 tags: [Auth]
44 summary: C7 Session introspection — current identity and scopes
45 description: |
46 Returns the verified identity and derived API scopes for the caller. Accepts only a
47 `Bearer` JWT in the `Authorization` header — no cookie required, making it safe to call
48 cross-origin from Scooling or any other consumer.
49
50 The response is derived entirely from the signed token — no database call is made.
51 Scopes are role-derived today (C4 will replace this with per-user explicit grants without
52 changing the response shape).
53 security:
54 - bearerAuth: []
55 responses:
56 '200':
57 description: Verified session
58 content:
59 application/json:
60 schema:
61 type: object
62 required: [sub, provider, id, name, role, iat, exp, scopes]
63 properties:
64 sub:
65 type: string
66 description: Canonical user ID (`provider:id`)
67 example: google:104164334692309763642
68 provider:
69 type: string
70 enum: [google, github]
71 id:
72 type: string
73 description: Provider-specific user ID
74 name:
75 type: string
76 description: Display name (empty for refresh-path tokens)
77 role:
78 type: string
79 enum: [admin, member]
80 iat:
81 type: integer
82 description: Token issued-at (Unix seconds)
83 exp:
84 type: integer
85 description: Token expires-at (Unix seconds)
86 scopes:
87 type: array
88 items: { type: string }
89 description: Derived API scopes. `admin` role → `[vault:read, vault:write, admin]`; `member` → `[vault:read, vault:write]`
90 example: [vault:read, vault:write]
91 '401':
92 description: Missing, expired, or tampered token
93 content:
94 application/json:
95 schema:
96 type: object
97 properties:
98 error: { type: string }
99 code: { type: string, enum: [UNAUTHORIZED] }
100
101 /auth/providers:
102 get:
103 tags: [Auth]
104 summary: OAuth providers configured
105 security: []
106 responses:
107 '200':
108 content:
109 application/json:
110 schema:
111 type: object
112 properties:
113 google: { type: boolean }
114 github: { type: boolean }
115
116 /notes/facets:
117 get:
118 tags: [Notes]
119 summary: Projects, tags, folders for filter dropdowns
120 responses:
121 '200':
122 content:
123 application/json:
124 schema:
125 type: object
126 properties:
127 projects: { type: array, items: { type: string } }
128 tags: { type: array, items: { type: string } }
129 folders: { type: array, items: { type: string } }
130
131 /notes:
132 get:
133 tags: [Notes]
134 summary: List notes
135 parameters:
136 - name: folder
137 in: query
138 schema: { type: string }
139 - name: project
140 in: query
141 schema: { type: string }
142 - name: tag
143 in: query
144 schema: { type: string }
145 - name: since
146 in: query
147 schema: { type: string }
148 - name: until
149 in: query
150 schema: { type: string }
151 - name: limit
152 in: query
153 schema: { type: integer, minimum: 0, maximum: 100 }
154 - name: offset
155 in: query
156 schema: { type: integer, minimum: 0 }
157 - name: order
158 in: query
159 schema: { type: string, enum: [date, date-asc] }
160 - name: fields
161 in: query
162 schema: { type: string, enum: [path, path+metadata, full] }
163 - name: count_only
164 in: query
165 schema: { type: boolean }
166 responses:
167 '200':
168 content:
169 application/json:
170 schema:
171 oneOf:
172 - type: object
173 properties:
174 notes: { type: array, items: { $ref: '#/components/schemas/NoteListItem' } }
175 total: { type: integer }
176 - type: object
177 properties:
178 total: { type: integer }
179 post:
180 tags: [Notes]
181 summary: Write or update a note
182 requestBody:
183 required: true
184 content:
185 application/json:
186 schema:
187 type: object
188 required: [path]
189 properties:
190 path: { type: string }
191 body: { type: string }
192 frontmatter: { type: object }
193 append: { type: boolean }
194 responses:
195 '200':
196 content:
197 application/json:
198 schema: { type: object, properties: { path: { type: string }, written: { type: boolean } } }
199 '400':
200 '500':
201 content:
202 application/json:
203 schema: { $ref: '#/components/schemas/Error' }
204
205 /notes/{path}:
206 get:
207 tags: [Notes]
208 summary: Get one note by path
209 parameters:
210 - name: path
211 in: path
212 required: true
213 schema: { type: string }
214 responses:
215 '200':
216 content:
217 application/json:
218 schema: { $ref: '#/components/schemas/NoteFull' }
219 '404':
220 content:
221 application/json:
222 schema: { $ref: '#/components/schemas/Error' }
223
224 /note-outline:
225 get:
226 tags: [Notes]
227 summary: Body-free NoteOutline headings for one note
228 description: >
229 Returns knowtation.note_outline/v1 metadata for one authorized vault-relative note.
230 The response excludes note body text, snippets, full frontmatter, absolute paths,
231 provider payloads, MCP resource URIs, summaries, vectors, OCR, PageIndex output,
232 persistence records, and write-back state.
233 parameters:
234 - name: path
235 in: query
236 required: true
237 schema: { type: string }
238 description: Vault-relative Markdown note path.
239 responses:
240 '200':
241 content:
242 application/json:
243 schema: { $ref: '#/components/schemas/NoteOutline' }
244 '400':
245 content:
246 application/json:
247 schema: { $ref: '#/components/schemas/Error' }
248 '401':
249 content:
250 application/json:
251 schema: { $ref: '#/components/schemas/Error' }
252 '403':
253 content:
254 application/json:
255 schema: { $ref: '#/components/schemas/Error' }
256 '404':
257 content:
258 application/json:
259 schema: { $ref: '#/components/schemas/Error' }
260 '502':
261 content:
262 application/json:
263 schema: { $ref: '#/components/schemas/Error' }
264
265 /document-tree:
266 get:
267 tags: [Notes]
268 summary: Body-free DocumentTree heading hierarchy for one note
269 description: >
270 Returns knowtation.document_tree/v0 metadata for one authorized vault-relative note.
271 The response excludes note body text, snippets, full frontmatter, absolute paths,
272 provider payloads, MCP resource URIs, summaries, vectors, OCR, PageIndex output,
273 persistence records, sidecars, LLM calls, and write-back state.
274 parameters:
275 - name: path
276 in: query
277 required: true
278 schema: { type: string }
279 description: Vault-relative Markdown note path.
280 responses:
281 '200':
282 content:
283 application/json:
284 schema: { $ref: '#/components/schemas/DocumentTree' }
285 '400':
286 content:
287 application/json:
288 schema: { $ref: '#/components/schemas/Error' }
289 '401':
290 content:
291 application/json:
292 schema: { $ref: '#/components/schemas/Error' }
293 '403':
294 content:
295 application/json:
296 schema: { $ref: '#/components/schemas/Error' }
297 '404':
298 content:
299 application/json:
300 schema: { $ref: '#/components/schemas/Error' }
301 '502':
302 content:
303 application/json:
304 schema: { $ref: '#/components/schemas/Error' }
305
306 /calendar/timeline:
307 get:
308 tags: [Calendar]
309 summary: Merged note-date and external-event timeline (self-hosted)
310 description: >
311 Returns knowtation.calendar_timeline/v0 items for an authorized vault.
312 Merges note-date buckets and stored calendar events. No OAuth tokens or connector secrets.
313 parameters:
314 - name: from
315 in: query
316 required: true
317 schema: { type: string }
318 description: Range start (YYYY-MM-DD or ISO8601).
319 - name: to
320 in: query
321 required: true
322 schema: { type: string }
323 description: Range end (YYYY-MM-DD or ISO8601).
324 - name: layers
325 in: query
326 required: false
327 schema: { type: string }
328 description: Comma-separated layers (`notes`, `events`). Default both.
329 - name: source_calendar_ids
330 in: query
331 required: false
332 schema: { type: string }
333 description: Comma-separated source calendar ids to include for the events layer.
334 responses:
335 '200':
336 content:
337 application/json:
338 schema: { $ref: '#/components/schemas/CalendarTimeline' }
339 '400':
340 content:
341 application/json:
342 schema: { $ref: '#/components/schemas/Error' }
343 '401':
344 content:
345 application/json:
346 schema: { $ref: '#/components/schemas/Error' }
347 '403':
348 content:
349 application/json:
350 schema: { $ref: '#/components/schemas/Error' }
351
352 /calendar/agent-context:
353 get:
354 tags: [Calendar]
355 summary: Tier-enforced calendar context for agents (self-hosted)
356 description: >
357 Returns knowtation.calendar_agent_context/v0 — redacted calendar events an agent
358 may see. Enforced server-side: calendars with enabled_for_agents=false contribute
359 nothing; per-calendar agent_context_tier_max and the org policy cap clamp the tier;
360 the v0 retrieval ceiling is tier 2. Agent visibility is independent of
361 enabled_for_display. Tier 1 omits the event summary; tier 0 returns no events.
362 Calendar text is untrusted prompt content.
363 parameters:
364 - name: from
365 in: query
366 required: true
367 schema: { type: string }
368 description: Range start (YYYY-MM-DD or ISO8601).
369 - name: to
370 in: query
371 required: true
372 schema: { type: string }
373 description: Range end (YYYY-MM-DD or ISO8601).
374 - name: agent_context_tier
375 in: query
376 required: true
377 schema: { type: integer, minimum: 0, maximum: 2 }
378 description: Requested agent tier (0 none, 1 busy blocks, 2 titles + label). Clamped by caps.
379 - name: source_calendar_ids
380 in: query
381 required: false
382 schema: { type: string }
383 description: Comma-separated source calendar ids to restrict the agent scope.
384 responses:
385 '200':
386 content:
387 application/json:
388 schema: { $ref: '#/components/schemas/CalendarAgentContext' }
389 '400':
390 content:
391 application/json:
392 schema: { $ref: '#/components/schemas/Error' }
393 '401':
394 content:
395 application/json:
396 schema: { $ref: '#/components/schemas/Error' }
397 '403':
398 content:
399 application/json:
400 schema: { $ref: '#/components/schemas/Error' }
401
402 /calendar/source-calendars:
403 get:
404 tags: [Calendar]
405 summary: List source calendars and display/agent toggles (self-hosted)
406 responses:
407 '200':
408 content:
409 application/json:
410 schema: { $ref: '#/components/schemas/SourceCalendarList' }
411 '401':
412 content:
413 application/json:
414 schema: { $ref: '#/components/schemas/Error' }
415 '403':
416 content:
417 application/json:
418 schema: { $ref: '#/components/schemas/Error' }
419
420 /calendar/source-calendars/{id}:
421 patch:
422 tags: [Calendar]
423 summary: Update source calendar display/agent toggles (self-hosted)
424 description: >
425 Partial update for enabled_for_display, enabled_for_agents, agent_context_tier_max (0–4),
426 and optional user_group. Org policy may cap agent_context_tier_max via
427 KNOWTATION_CALENDAR_AGENT_TIER_MAX_CAP or data/hub_calendar_policy.json.
428 parameters:
429 - name: id
430 in: path
431 required: true
432 schema: { type: string }
433 description: Source calendar id.
434 requestBody:
435 required: true
436 content:
437 application/json:
438 schema: { $ref: '#/components/schemas/SourceCalendarPatchRequest' }
439 responses:
440 '200':
441 content:
442 application/json:
443 schema: { $ref: '#/components/schemas/SourceCalendarPatchResult' }
444 '400':
445 content:
446 application/json:
447 schema: { $ref: '#/components/schemas/Error' }
448 '401':
449 content:
450 application/json:
451 schema: { $ref: '#/components/schemas/Error' }
452 '403':
453 content:
454 application/json:
455 schema: { $ref: '#/components/schemas/Error' }
456 '404':
457 content:
458 application/json:
459 schema: { $ref: '#/components/schemas/Error' }
460
461 /calendar/events/import:
462 post:
463 tags: [Calendar]
464 summary: Import ICS text into the local event store (read-only, self-hosted)
465 requestBody:
466 required: true
467 content:
468 application/json:
469 schema: { $ref: '#/components/schemas/CalendarIcsImportRequest' }
470 responses:
471 '200':
472 content:
473 application/json:
474 schema: { $ref: '#/components/schemas/CalendarIcsImportResult' }
475 '400':
476 content:
477 application/json:
478 schema: { $ref: '#/components/schemas/Error' }
479 '401':
480 content:
481 application/json:
482 schema: { $ref: '#/components/schemas/Error' }
483 '403':
484 content:
485 application/json:
486 schema: { $ref: '#/components/schemas/Error' }
487
488 /flows:
489 get:
490 tags: [Flows]
491 summary: List scope-visible flows (content-minimized)
492 description: >
493 Returns knowtation.flow_list/v0 summaries for flows visible in the caller's
494 authorized workspace scope. Scope query param narrows only — never widens.
495 Step bodies are never included in list responses.
496 parameters:
497 - name: scope
498 in: query
499 schema: { type: string, enum: [personal, project, org] }
500 description: Narrow within authorized scopes only.
501 - name: tag
502 in: query
503 schema: { type: string }
504 description: Filter by single tag membership.
505 - name: limit
506 in: query
507 schema: { type: integer, minimum: 1, maximum: 200 }
508 description: Max summaries (default 200).
509 responses:
510 '200':
511 content:
512 application/json:
513 schema: { $ref: '#/components/schemas/FlowListResponse' }
514 '400':
515 content:
516 application/json:
517 schema: { $ref: '#/components/schemas/Error' }
518 '401':
519 content:
520 application/json:
521 schema: { $ref: '#/components/schemas/Error' }
522 '403':
523 content:
524 application/json:
525 schema: { $ref: '#/components/schemas/Error' }
526 post:
527 tags: [Flows]
528 summary: Propose a new Flow (review-before-write)
529 description: >
530 Validates a knowtation.flow/v0 + flow_step/v0 bundle, resolves write
531 authority server-side (scope × role, deny-by-default), and creates a
532 standard proposal targeting the Flow's mirror note (SD-4). Returns a
533 knowtation.flow_proposal/v0 envelope (pointers/labels only). Gated by
534 FLOW_AUTHORING_WRITES — when off returns 403 FLOW_AUTHORING_DISABLED.
535 No Flow index write happens here; the index changes only at approve→apply.
536 requestBody:
537 required: true
538 content:
539 application/json:
540 schema: { $ref: '#/components/schemas/FlowProposeRequest' }
541 responses:
542 '201':
543 content:
544 application/json:
545 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
546 '400':
547 content:
548 application/json:
549 schema: { $ref: '#/components/schemas/Error' }
550 '401':
551 content:
552 application/json:
553 schema: { $ref: '#/components/schemas/Error' }
554 '403':
555 content:
556 application/json:
557 schema: { $ref: '#/components/schemas/Error' }
558 '409':
559 content:
560 application/json:
561 schema: { $ref: '#/components/schemas/Error' }
562
563 /flows/import:
564 post:
565 tags: [Flows]
566 summary: Import a portable Flow bundle as a scope-checked proposal
567 description: >
568 Routes a portable { flow, steps } bundle through the same propose path.
569 The bundle scope is validated against the actor's write tier; unwritable
570 ⇒ 403 FLOW_IMPORT_SCOPE_DENIED, malformed ⇒ 400 FLOW_IMPORT_BUNDLE_MALFORMED.
571 Lineage pointers (external_ref / source_vault_hint) are preserved. Never
572 auto-applied — creates a proposed proposal. Gated by FLOW_AUTHORING_WRITES.
573 requestBody:
574 required: true
575 content:
576 application/json:
577 schema: { $ref: '#/components/schemas/FlowImportRequest' }
578 responses:
579 '201':
580 content:
581 application/json:
582 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
583 '400':
584 content:
585 application/json:
586 schema: { $ref: '#/components/schemas/Error' }
587 '401':
588 content:
589 application/json:
590 schema: { $ref: '#/components/schemas/Error' }
591 '403':
592 content:
593 application/json:
594 schema: { $ref: '#/components/schemas/Error' }
595 '409':
596 content:
597 application/json:
598 schema: { $ref: '#/components/schemas/Error' }
599
600 /flows/capture/observe:
601 post:
602 tags: [Flows]
603 summary: Observe content-minimized session signals (capture detection)
604 description: >
605 Runs bounded structural detectors when FLOW_CAPTURE_DETECTION_ENABLED is on.
606 Creates/updates flow_candidate/v0 records; returns content-minimized summaries.
607 When detection is off, returns detection_authorized=false with no store mutation.
608 requestBody:
609 required: true
610 content:
611 application/json:
612 schema:
613 type: object
614 required: [session_id, step_sequence_refs, observed_counts]
615 responses:
616 '200':
617 description: Observe envelope
618 '400':
619 content:
620 application/json:
621 schema: { $ref: '#/components/schemas/Error' }
622 '403':
623 content:
624 application/json:
625 schema: { $ref: '#/components/schemas/Error' }
626
627 /flows/candidates:
628 get:
629 tags: [Flows]
630 summary: List flow capture candidates (read store)
631 description: Returns pending_review candidate summaries; read path does not require detection sub-gate.
632 parameters:
633 - name: scope
634 in: query
635 schema: { type: string, enum: [personal, project, org] }
636 - name: include_low_confidence
637 in: query
638 schema: { type: boolean }
639 - name: limit
640 in: query
641 schema: { type: integer, minimum: 1, maximum: 50 }
642 responses:
643 '200':
644 description: Candidate list envelope
645 '400':
646 content:
647 application/json:
648 schema: { $ref: '#/components/schemas/Error' }
649
650 /flows/candidates/{candidate_id}/propose:
651 post:
652 tags: [Flows]
653 summary: Propose candidate promotion (review-before-write)
654 description: >
655 Creates a flow_candidate_promote or flow_candidate_merge proposal.
656 Gated by FLOW_CAPTURE_WRITES_ENABLED (default off).
657 parameters:
658 - name: candidate_id
659 in: path
660 required: true
661 schema: { type: string }
662 requestBody:
663 required: true
664 content:
665 application/json:
666 schema:
667 type: object
668 required: [confirmed_scope, intent]
669 responses:
670 '201':
671 description: Capture proposal envelope
672 '403':
673 content:
674 application/json:
675 schema: { $ref: '#/components/schemas/Error' }
676 '404':
677 content:
678 application/json:
679 schema: { $ref: '#/components/schemas/Error' }
680 '409':
681 content:
682 application/json:
683 schema: { $ref: '#/components/schemas/Error' }
684
685 /flows/candidates/{candidate_id}/dismiss:
686 post:
687 tags: [Flows]
688 summary: Propose candidate dismissal
689 description: >
690 Creates a flow_candidate_dismiss proposal; on approve candidate status becomes rejected.
691 Gated by FLOW_CAPTURE_WRITES_ENABLED (default off).
692 parameters:
693 - name: candidate_id
694 in: path
695 required: true
696 schema: { type: string }
697 requestBody:
698 required: true
699 content:
700 application/json:
701 schema:
702 type: object
703 required: [intent]
704 responses:
705 '201':
706 description: Capture proposal envelope
707 '403':
708 content:
709 application/json:
710 schema: { $ref: '#/components/schemas/Error' }
711 '404':
712 content:
713 application/json:
714 schema: { $ref: '#/components/schemas/Error' }
715
716 /flows/{id}/proposals:
717 post:
718 tags: [Flows]
719 summary: Propose an edit to an existing Flow (review-before-write)
720 description: >
721 Like POST /flows but for an edit. Requires base_version + base_state_id
722 (the flowst1_ optimistic-concurrency token); a mismatch at propose or
723 approve time ⇒ 409 FLOW_LINEAGE_CONFLICT. flow.version must be strictly
724 greater than base_version. Editing a flow the actor cannot read ⇒ 404
725 unknown_flow (no existence leak). Gated by FLOW_AUTHORING_WRITES.
726 parameters:
727 - name: id
728 in: path
729 required: true
730 schema: { type: string }
731 description: Flow id (flow_<slug>); must match the bundle's flow_id.
732 requestBody:
733 required: true
734 content:
735 application/json:
736 schema: { $ref: '#/components/schemas/FlowProposeEditRequest' }
737 responses:
738 '201':
739 content:
740 application/json:
741 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
742 '400':
743 content:
744 application/json:
745 schema: { $ref: '#/components/schemas/Error' }
746 '401':
747 content:
748 application/json:
749 schema: { $ref: '#/components/schemas/Error' }
750 '403':
751 content:
752 application/json:
753 schema: { $ref: '#/components/schemas/Error' }
754 '404':
755 content:
756 application/json:
757 schema: { $ref: '#/components/schemas/Error' }
758 '409':
759 content:
760 application/json:
761 schema: { $ref: '#/components/schemas/Error' }
762
763 /flows/{id}/projection:
764 get:
765 tags: [Flows]
766 summary: Derive a read-only harness projection of a canonical flow
767 description: >
768 Renders the canonical flow (latest visible, or pinned ?version) into the requested
769 harness as knowtation.flow_project/v0. Derived and read-only — generated_from_canonical
770 is always true and editable is always false. No secrets appear in rendered text.
771 parameters:
772 - name: id
773 in: path
774 required: true
775 schema: { type: string }
776 - name: harness
777 in: query
778 required: true
779 schema:
780 type: string
781 enum: [cursor_rule, cursor_skill, mcp_prompt, cli_runbook, agent_bundle]
782 - name: version
783 in: query
784 schema: { type: string }
785 responses:
786 '200':
787 content:
788 application/json:
789 schema: { $ref: '#/components/schemas/FlowProjectResponse' }
790 '400':
791 content:
792 application/json:
793 schema: { $ref: '#/components/schemas/Error' }
794 '401':
795 content:
796 application/json:
797 schema: { $ref: '#/components/schemas/Error' }
798 '403':
799 content:
800 application/json:
801 schema: { $ref: '#/components/schemas/Error' }
802 '404':
803 content:
804 application/json:
805 schema: { $ref: '#/components/schemas/Error' }
806
807 /flows/{id}/external-grants:
808 post:
809 tags: [Flows]
810 summary: Mint a short-lived external-agent grant (gated; default off)
811 description: >
812 Mints knowtation.flow_external_grant/v0 for a pinned flow version and requested tools.
813 Returns a one-time bearer at mint only. Requires FLOW_EXTERNAL_AGENT_ENABLED.
814 parameters:
815 - name: id
816 in: path
817 required: true
818 schema: { type: string }
819 requestBody:
820 required: true
821 content:
822 application/json:
823 schema: { $ref: '#/components/schemas/FlowExternalGrantMintRequest' }
824 responses:
825 '201':
826 content:
827 application/json:
828 schema: { $ref: '#/components/schemas/FlowExternalGrantMintResponse' }
829 '400':
830 content:
831 application/json:
832 schema: { $ref: '#/components/schemas/Error' }
833 '403':
834 content:
835 application/json:
836 schema: { $ref: '#/components/schemas/Error' }
837 '404':
838 content:
839 application/json:
840 schema: { $ref: '#/components/schemas/Error' }
841
842 /flows/external-grants:
843 get:
844 tags: [Flows]
845 summary: List external-agent grant metadata (no bearer)
846 parameters:
847 - name: flow_id
848 in: query
849 schema: { type: string }
850 responses:
851 '200':
852 content:
853 application/json:
854 schema: { $ref: '#/components/schemas/FlowExternalGrantListResponse' }
855 '403':
856 content:
857 application/json:
858 schema: { $ref: '#/components/schemas/Error' }
859
860 /flows/external-grants/{grant_id}:
861 delete:
862 tags: [Flows]
863 summary: Revoke an external-agent grant
864 parameters:
865 - name: grant_id
866 in: path
867 required: true
868 schema: { type: string }
869 responses:
870 '200':
871 content:
872 application/json:
873 schema: { $ref: '#/components/schemas/FlowExternalGrant' }
874 '403':
875 content:
876 application/json:
877 schema: { $ref: '#/components/schemas/Error' }
878 '404':
879 content:
880 application/json:
881 schema: { $ref: '#/components/schemas/Error' }
882
883 /tasks:
884 get:
885 tags: [Tasks]
886 summary: List scope-visible tasks (content-minimized)
887 description: >
888 Returns knowtation.task_list/v0 summaries for tasks visible in the caller's
889 authorized workspace scope. Scope query param narrows only — never widens.
890 List responses never include assignee refs or artifact_links.
891 parameters:
892 - name: scope
893 in: query
894 schema: { type: string, enum: [personal, project, org] }
895 description: Narrow within authorized scopes only.
896 - name: workspace_id
897 in: query
898 schema: { type: string }
899 description: Filter by workspace_id equality.
900 - name: status
901 in: query
902 schema:
903 type: string
904 enum: [pending, in_progress, blocked, done, cancelled]
905 - name: kind
906 in: query
907 schema:
908 type: string
909 enum: [personal, assignment, mentor_checkin, org_work_job]
910 - name: limit
911 in: query
912 schema: { type: integer, minimum: 1, maximum: 500 }
913 description: Max summaries (default 500).
914 responses:
915 '200':
916 content:
917 application/json:
918 schema: { $ref: '#/components/schemas/TaskListResponse' }
919 '400':
920 content:
921 application/json:
922 schema: { $ref: '#/components/schemas/Error' }
923 '401':
924 content:
925 application/json:
926 schema: { $ref: '#/components/schemas/Error' }
927 '403':
928 content:
929 application/json:
930 schema: { $ref: '#/components/schemas/Error' }
931
932 /tasks/{id}:
933 get:
934 tags: [Tasks]
935 summary: Get one authorized task
936 description: >
937 Returns knowtation.task_get/v0 with the full task record when the caller
938 is authorized for the task scope. Missing or invisible tasks return 404
939 unknown_task (no existence leak).
940 parameters:
941 - name: id
942 in: path
943 required: true
944 schema: { type: string }
945 responses:
946 '200':
947 content:
948 application/json:
949 schema: { $ref: '#/components/schemas/TaskGetResponse' }
950 '400':
951 content:
952 application/json:
953 schema: { $ref: '#/components/schemas/Error' }
954 '401':
955 content:
956 application/json:
957 schema: { $ref: '#/components/schemas/Error' }
958 '403':
959 content:
960 application/json:
961 schema: { $ref: '#/components/schemas/Error' }
962 '404':
963 content:
964 application/json:
965 schema: { $ref: '#/components/schemas/Error' }
966
967 /attachments:
968 get:
969 tags: [Attachments]
970 summary: List scope-visible attachments (content-minimized)
971 description: >
972 Returns knowtation.attachment_list/v0 summaries for attachments visible in
973 the caller's authorized workspace scope. Scope query param narrows only — never widens.
974 List responses never include linked_note_refs, byte_size, mime_type, or agent_visible.
975 parameters:
976 - name: scope
977 in: query
978 schema: { type: string, enum: [personal, project, org] }
979 description: Narrow within authorized scopes only.
980 - name: note_ref
981 in: query
982 schema: { type: string }
983 description: Filter attachments linked to a specific note (note:path).
984 - name: source
985 in: query
986 schema:
987 type: string
988 enum: [vault_file, mist_blob, embedded_url, connector_ref]
989 - name: mime_class
990 in: query
991 schema:
992 type: string
993 enum: [image, video, audio, document, unknown]
994 - name: storage_kind
995 in: query
996 schema:
997 type: string
998 enum: [vault_blob, external_link]
999 - name: agent_visible
1000 in: query
1001 schema: { type: boolean }
1002 description: When true, return only attachments with agent_visible consent.
1003 - name: limit
1004 in: query
1005 schema: { type: integer, minimum: 1, maximum: 500 }
1006 description: Max summaries (default 500).
1007 responses:
1008 '200':
1009 content:
1010 application/json:
1011 schema: { $ref: '#/components/schemas/AttachmentListResponse' }
1012 '400':
1013 content:
1014 application/json:
1015 schema: { $ref: '#/components/schemas/Error' }
1016 '401':
1017 content:
1018 application/json:
1019 schema: { $ref: '#/components/schemas/Error' }
1020 '403':
1021 content:
1022 application/json:
1023 schema: { $ref: '#/components/schemas/Error' }
1024
1025 '404':
1026 content:
1027 application/json:
1028 schema: { $ref: '#/components/schemas/Error' }
1029
1030 /attachments/link-proposals:
1031 post:
1032 tags: [Attachments]
1033 summary: Propose an external media link (review-before-write)
1034 description: >
1035 Creates a media_external_link proposal. Gated by MEDIA_EXTERNAL_LINK_ENABLED (default off).
1036 Requires an active import consent and allowlisted connector. Never fetches opaque_ref.
1037 requestBody:
1038 required: true
1039 content:
1040 application/json:
1041 schema:
1042 type: object
1043 required: [intent, scope, connector_id, opaque_ref, consent_id]
1044 properties:
1045 intent: { type: string }
1046 scope: { type: string, enum: [personal, project, org] }
1047 connector_id: { type: string }
1048 opaque_ref: { type: string }
1049 consent_id: { type: string }
1050 display_label: { type: string }
1051 responses:
1052 '201':
1053 content:
1054 application/json:
1055 schema: { $ref: '#/components/schemas/MediaProposalResponse' }
1056 '403':
1057 content:
1058 application/json:
1059 schema: { $ref: '#/components/schemas/Error' }
1060
1061 /attachments/attach-proposals:
1062 post:
1063 tags: [Attachments]
1064 summary: Propose attaching media to a note (review-before-write)
1065 description: >
1066 Creates a media_attach proposal. Gated by MEDIA_ATTACH_ENABLED (default off).
1067 requestBody:
1068 required: true
1069 content:
1070 application/json:
1071 schema:
1072 type: object
1073 required: [intent, scope, attachment_id, note_ref, base_state_id]
1074 properties:
1075 intent: { type: string }
1076 scope: { type: string, enum: [personal, project, org] }
1077 attachment_id: { type: string }
1078 note_ref: { type: string }
1079 base_state_id: { type: string }
1080 responses:
1081 '201':
1082 content:
1083 application/json:
1084 schema: { $ref: '#/components/schemas/MediaProposalResponse' }
1085 '403':
1086 content:
1087 application/json:
1088 schema: { $ref: '#/components/schemas/Error' }
1089
1090 /attachments/import-consents:
1091 get:
1092 tags: [Attachments]
1093 summary: List import consents (read-only)
1094 parameters:
1095 - name: scope
1096 in: query
1097 schema: { type: string, enum: [personal, project, org] }
1098 responses:
1099 '200':
1100 content:
1101 application/json:
1102 schema:
1103 type: object
1104 required: [schema, vault_id, consents]
1105 properties:
1106 schema:
1107 type: string
1108 enum: [knowtation.media_import_consent_list/v0]
1109 vault_id: { type: string }
1110 consents:
1111 type: array
1112 items:
1113 type: object
1114 post:
1115 tags: [Attachments]
1116 summary: Grant import consent for external linking
1117 description: Requires MEDIA_EXTERNAL_LINK_ENABLED. Not exposed as MCP write tool.
1118 requestBody:
1119 required: true
1120 content:
1121 application/json:
1122 schema:
1123 type: object
1124 required: [connector_id, scope]
1125 properties:
1126 connector_id: { type: string }
1127 scope: { type: string, enum: [personal, project, org] }
1128 expires_at: { type: [string, 'null'] }
1129 responses:
1130 '201':
1131 content:
1132 application/json:
1133 schema:
1134 type: object
1135 delete:
1136 tags: [Attachments]
1137 summary: Revoke import consent (not supported at collection path)
1138 responses:
1139 '405':
1140 content:
1141 application/json:
1142 schema: { $ref: '#/components/schemas/Error' }
1143
1144 /attachments/import-consents/{id}:
1145 delete:
1146 tags: [Attachments]
1147 summary: Revoke an import consent by id
1148 parameters:
1149 - name: id
1150 in: path
1151 required: true
1152 schema: { type: string }
1153 responses:
1154 '200':
1155 content:
1156 application/json:
1157 schema:
1158 type: object
1159 '404':
1160 content:
1161 application/json:
1162 schema: { $ref: '#/components/schemas/Error' }
1163
1164 /attachments/{id}:
1165 get:
1166 tags: [Attachments]
1167 summary: Get one authorized attachment
1168 description: >
1169 Returns knowtation.attachment_get/v0 with the full attachment record when
1170 the caller is authorized. Missing or invisible attachments return 404
1171 unknown_attachment (no existence leak).
1172 parameters:
1173 - name: id
1174 in: path
1175 required: true
1176 schema: { type: string }
1177 responses:
1178 '200':
1179 content:
1180 application/json:
1181 schema: { $ref: '#/components/schemas/AttachmentGetResponse' }
1182 '400':
1183 content:
1184 application/json:
1185 schema: { $ref: '#/components/schemas/Error' }
1186 '401':
1187 content:
1188 application/json:
1189 schema: { $ref: '#/components/schemas/Error' }
1190 '403':
1191 content:
1192 application/json:
1193 schema: { $ref: '#/components/schemas/Error' }
1194 '404':
1195 content:
1196 application/json:
1197 schema: { $ref: '#/components/schemas/Error' }
1198
1199 /tasks/proposals:
1200 post:
1201 tags: [Tasks]
1202 summary: Propose a one-time task write (SD-4; gated; default off)
1203 description: >
1204 Typed facade over /proposals for task_create, task_status_update, task_assign,
1205 and task_artifact_link. Requires TASK_WRITES_ENABLED (default off).
1206 requestBody:
1207 required: true
1208 content:
1209 application/json:
1210 schema: { $ref: '#/components/schemas/TaskWriteProposalRequest' }
1211 responses:
1212 '201':
1213 content:
1214 application/json:
1215 schema: { $ref: '#/components/schemas/TaskProposalResponse' }
1216 '403':
1217 content:
1218 application/json:
1219 schema: { $ref: '#/components/schemas/Error' }
1220 '409':
1221 content:
1222 application/json:
1223 schema: { $ref: '#/components/schemas/Error' }
1224
1225 /task-loops/proposals:
1226 post:
1227 tags: [Tasks]
1228 summary: Propose a task loop series write (SD-4; gated; default off)
1229 description: >
1230 task_loop_create, task_loop_pause, or task_loop_cancel proposal. Requires TASK_WRITES_ENABLED.
1231 requestBody:
1232 required: true
1233 content:
1234 application/json:
1235 schema: { $ref: '#/components/schemas/TaskLoopWriteProposalRequest' }
1236 responses:
1237 '201':
1238 content:
1239 application/json:
1240 schema: { $ref: '#/components/schemas/TaskProposalResponse' }
1241 '403':
1242 content:
1243 application/json:
1244 schema: { $ref: '#/components/schemas/Error' }
1245
1246 /task-loops/{loop_id}/instances/proposals:
1247 post:
1248 tags: [Tasks]
1249 summary: Propose materializing one loop occurrence task (SD-4; gated; default off)
1250 parameters:
1251 - name: loop_id
1252 in: path
1253 required: true
1254 schema: { type: string }
1255 requestBody:
1256 required: true
1257 content:
1258 application/json:
1259 schema: { $ref: '#/components/schemas/TaskInstanceMaterializeRequest' }
1260 responses:
1261 '201':
1262 content:
1263 application/json:
1264 schema: { $ref: '#/components/schemas/TaskInstanceProposalResponse' }
1265 '403':
1266 content:
1267 application/json:
1268 schema: { $ref: '#/components/schemas/Error' }
1269 '409':
1270 content:
1271 application/json:
1272 schema: { $ref: '#/components/schemas/Error' }
1273
1274 /agents/identities:
1275 post:
1276 tags: [Delegation]
1277 summary: Propose agent identity registration (SD-4; gated; default off)
1278 description: >
1279 Creates an SD-4 proposal with intent agent_identity_register. Requires DELEGATION_ENABLED.
1280 requestBody:
1281 required: true
1282 content:
1283 application/json:
1284 schema: { $ref: '#/components/schemas/AgentIdentityRegisterRequest' }
1285 responses:
1286 '201':
1287 content:
1288 application/json:
1289 schema: { $ref: '#/components/schemas/DelegationProposalResponse' }
1290 '403':
1291 content:
1292 application/json:
1293 schema: { $ref: '#/components/schemas/Error' }
1294 get:
1295 tags: [Delegation]
1296 summary: List agent identities (gated; default off)
1297 parameters:
1298 - name: kind
1299 in: query
1300 schema:
1301 type: string
1302 enum: [user_owned, org_owned, delegate]
1303 - name: status
1304 in: query
1305 schema:
1306 type: string
1307 enum: [active, suspended, revoked]
1308 responses:
1309 '200':
1310 content:
1311 application/json:
1312 schema: { $ref: '#/components/schemas/AgentIdentityListResponse' }
1313 '403':
1314 content:
1315 application/json:
1316 schema: { $ref: '#/components/schemas/Error' }
1317
1318 /delegation/consents:
1319 post:
1320 tags: [Delegation]
1321 summary: Propose delegation consent (SD-4; gated; default off)
1322 requestBody:
1323 required: true
1324 content:
1325 application/json:
1326 schema: { $ref: '#/components/schemas/DelegationConsentProposeRequest' }
1327 responses:
1328 '201':
1329 content:
1330 application/json:
1331 schema: { $ref: '#/components/schemas/DelegationConsentProposeResponse' }
1332 '403':
1333 content:
1334 application/json:
1335 schema: { $ref: '#/components/schemas/Error' }
1336
1337 /delegation/consents/{consent_id}:
1338 delete:
1339 tags: [Delegation]
1340 summary: Revoke delegation consent
1341 parameters:
1342 - name: consent_id
1343 in: path
1344 required: true
1345 schema: { type: string }
1346 responses:
1347 '200':
1348 content:
1349 application/json:
1350 schema: { $ref: '#/components/schemas/DelegationConsent' }
1351 '403':
1352 content:
1353 application/json:
1354 schema: { $ref: '#/components/schemas/Error' }
1355 '404':
1356 content:
1357 application/json:
1358 schema: { $ref: '#/components/schemas/Error' }
1359
1360 /delegation/grants:
1361 post:
1362 tags: [Delegation]
1363 summary: Mint short-lived delegation grant (gated; default off)
1364 requestBody:
1365 required: true
1366 content:
1367 application/json:
1368 schema: { $ref: '#/components/schemas/DelegationGrantMintRequest' }
1369 responses:
1370 '201':
1371 content:
1372 application/json:
1373 schema: { $ref: '#/components/schemas/DelegationGrantMintResponse' }
1374 '403':
1375 content:
1376 application/json:
1377 schema: { $ref: '#/components/schemas/Error' }
1378 '404':
1379 content:
1380 application/json:
1381 schema: { $ref: '#/components/schemas/Error' }
1382 get:
1383 tags: [Delegation]
1384 summary: List delegation grant metadata (no bearer)
1385 parameters:
1386 - name: actor_agent_id
1387 in: query
1388 schema: { type: string }
1389 responses:
1390 '200':
1391 content:
1392 application/json:
1393 schema: { $ref: '#/components/schemas/DelegationGrantListResponse' }
1394 '403':
1395 content:
1396 application/json:
1397 schema: { $ref: '#/components/schemas/Error' }
1398
1399 /delegation/grants/{grant_id}:
1400 delete:
1401 tags: [Delegation]
1402 summary: Revoke delegation grant
1403 parameters:
1404 - name: grant_id
1405 in: path
1406 required: true
1407 schema: { type: string }
1408 responses:
1409 '200':
1410 content:
1411 application/json:
1412 schema: { $ref: '#/components/schemas/DelegationGrant' }
1413 '403':
1414 content:
1415 application/json:
1416 schema: { $ref: '#/components/schemas/Error' }
1417 '404':
1418 content:
1419 application/json:
1420 schema: { $ref: '#/components/schemas/Error' }
1421
1422 /delegation/audit:
1423 post:
1424 tags: [Delegation]
1425 summary: Append delegation audit entry (pointer-safe)
1426 requestBody:
1427 required: true
1428 content:
1429 application/json:
1430 schema: { $ref: '#/components/schemas/DelegationAuditAppendRequest' }
1431 responses:
1432 '201':
1433 content:
1434 application/json:
1435 schema: { $ref: '#/components/schemas/DelegationAudit' }
1436 '403':
1437 content:
1438 application/json:
1439 schema: { $ref: '#/components/schemas/Error' }
1440
1441 /flows/{id}:
1442 get:
1443 tags: [Flows]
1444 summary: Get one flow definition + ordered steps
1445 description: >
1446 Returns knowtation.flow_get/v0 with full flow definition and steps in ascending
1447 ordinal order. Missing and scope-invisible flows both return 404 unknown_flow.
1448 Step text is untrusted input — returned verbatim as data.
1449 parameters:
1450 - name: id
1451 in: path
1452 required: true
1453 schema: { type: string }
1454 description: Flow id (flow_<slug>).
1455 - name: version
1456 in: query
1457 schema: { type: string }
1458 description: Pin semver version; default latest visible.
1459 responses:
1460 '200':
1461 content:
1462 application/json:
1463 schema: { $ref: '#/components/schemas/FlowGetResponse' }
1464 '400':
1465 content:
1466 application/json:
1467 schema: { $ref: '#/components/schemas/Error' }
1468 '401':
1469 content:
1470 application/json:
1471 schema: { $ref: '#/components/schemas/Error' }
1472 '403':
1473 content:
1474 application/json:
1475 schema: { $ref: '#/components/schemas/Error' }
1476 '404':
1477 content:
1478 application/json:
1479 schema: { $ref: '#/components/schemas/Error' }
1480
1481 /flow-runs/{run_id}:
1482 get:
1483 tags: [Flows]
1484 summary: Get one flow run by run id or portable run_ref
1485 description: >
1486 Returns knowtation.flow_run/v0 for a scope-visible run. Accepts canonical
1487 run_id (run_…) or portable run_ref (flow_run:…). Missing and
1488 scope-invisible runs both return 404 unknown_run.
1489 parameters:
1490 - name: run_id
1491 in: path
1492 required: true
1493 schema: { type: string }
1494 responses:
1495 '200':
1496 content:
1497 application/json:
1498 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1499 '404':
1500 content:
1501 application/json:
1502 schema: { $ref: '#/components/schemas/Error' }
1503
1504 /flows/{id}/runs:
1505 get:
1506 tags: [Flows]
1507 summary: List runs for a flow
1508 parameters:
1509 - name: id
1510 in: path
1511 required: true
1512 schema: { type: string }
1513 responses:
1514 '200':
1515 content:
1516 application/json:
1517 schema: { $ref: '#/components/schemas/FlowRunListResponse' }
1518 post:
1519 tags: [Flows]
1520 summary: Start a flow run
1521 description: >
1522 Gated by FLOW_RUN_WRITES_ENABLED (default off). Pins flow_version for the run life.
1523 parameters:
1524 - name: id
1525 in: path
1526 required: true
1527 schema: { type: string }
1528 requestBody:
1529 required: true
1530 content:
1531 application/json:
1532 schema:
1533 type: object
1534 required: [flow_version]
1535 properties:
1536 flow_version: { type: string }
1537 task_ref: { type: string }
1538 external_ref: { type: string }
1539 responses:
1540 '201':
1541 content:
1542 application/json:
1543 schema: { $ref: '#/components/schemas/FlowRunStartResponse' }
1544 '403':
1545 content:
1546 application/json:
1547 schema: { $ref: '#/components/schemas/Error' }
1548
1549 /flows/{id}/runs/{run_id}:
1550 get:
1551 tags: [Flows]
1552 summary: Get one flow run
1553 parameters:
1554 - name: id
1555 in: path
1556 required: true
1557 schema: { type: string }
1558 - name: run_id
1559 in: path
1560 required: true
1561 schema: { type: string }
1562 responses:
1563 '200':
1564 content:
1565 application/json:
1566 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1567 post:
1568 tags: [Flows]
1569 summary: Advance, record evidence, execute automatable, or submit review
1570 description: >
1571 Use dedicated sub-paths (/advance, /evidence, /execute-automatable, /submit-review).
1572 Run writes gated by FLOW_RUN_WRITES_ENABLED; automatable by FLOW_AUTOMATABLE_EXECUTION_ENABLED.
1573
1574 /flows/{id}/runs/{run_id}/advance:
1575 post:
1576 tags: [Flows]
1577 summary: Advance a step manually
1578 parameters:
1579 - name: id
1580 in: path
1581 required: true
1582 schema: { type: string }
1583 - name: run_id
1584 in: path
1585 required: true
1586 schema: { type: string }
1587 requestBody:
1588 required: true
1589 content:
1590 application/json:
1591 schema:
1592 type: object
1593 required: [step_id, to_status]
1594 properties:
1595 step_id: { type: string }
1596 to_status: { type: string }
1597 skip_reason: { type: string }
1598 responses:
1599 '200':
1600 content:
1601 application/json:
1602 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1603
1604 /flows/{id}/runs/{run_id}/evidence:
1605 post:
1606 tags: [Flows]
1607 summary: Record evidence pointer on a step
1608 parameters:
1609 - name: id
1610 in: path
1611 required: true
1612 schema: { type: string }
1613 - name: run_id
1614 in: path
1615 required: true
1616 schema: { type: string }
1617 requestBody:
1618 required: true
1619 content:
1620 application/json:
1621 schema:
1622 type: object
1623 required: [step_id, evidence_ref, pointer_kind]
1624 properties:
1625 step_id: { type: string }
1626 evidence_ref: { type: string }
1627 pointer_kind: { type: string }
1628 responses:
1629 '200':
1630 content:
1631 application/json:
1632 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1633
1634 /flows/{id}/runs/{run_id}/execute-automatable:
1635 post:
1636 tags: [Flows]
1637 summary: Execute an automatable step (server orchestration stub)
1638 description: Requires valid knowtation.flow_execution_consent/v0. Gated by FLOW_AUTOMATABLE_EXECUTION_ENABLED.
1639 parameters:
1640 - name: id
1641 in: path
1642 required: true
1643 schema: { type: string }
1644 - name: run_id
1645 in: path
1646 required: true
1647 schema: { type: string }
1648 requestBody:
1649 required: true
1650 content:
1651 application/json:
1652 schema:
1653 type: object
1654 required: [step_id, consent_id]
1655 properties:
1656 step_id: { type: string }
1657 consent_id: { type: string }
1658 model_lane: { type: string }
1659 dry_run: { type: boolean }
1660 responses:
1661 '200':
1662 content:
1663 application/json:
1664 schema: { $ref: '#/components/schemas/FlowExecuteAutomatableResponse' }
1665
1666 /flows/{id}/runs/{run_id}/submit-review:
1667 post:
1668 tags: [Flows]
1669 summary: Submit run outcome to review tray
1670 parameters:
1671 - name: id
1672 in: path
1673 required: true
1674 schema: { type: string }
1675 - name: run_id
1676 in: path
1677 required: true
1678 schema: { type: string }
1679 requestBody:
1680 required: true
1681 content:
1682 application/json:
1683 schema:
1684 type: object
1685 required: [intent]
1686 properties:
1687 intent: { type: string }
1688 responses:
1689 '200':
1690 content:
1691 application/json:
1692 schema: { $ref: '#/components/schemas/FlowRunSubmitReviewResponse' }
1693
1694 /flows/{id}/runs/{run_id}/consent:
1695 post:
1696 tags: [Flows]
1697 summary: Mint execution consent for automatable steps
1698 parameters:
1699 - name: id
1700 in: path
1701 required: true
1702 schema: { type: string }
1703 - name: run_id
1704 in: path
1705 required: true
1706 schema: { type: string }
1707 requestBody:
1708 required: true
1709 content:
1710 application/json:
1711 schema:
1712 type: object
1713 required: [allowed_lanes, cost_cap_units]
1714 properties:
1715 allowed_lanes: { type: array, items: { type: string } }
1716 cost_cap_units: { type: integer }
1717 ttl_seconds: { type: integer }
1718 responses:
1719 '201':
1720 content:
1721 application/json:
1722 schema: { $ref: '#/components/schemas/FlowExecutionConsentMintResponse' }
1723
1724 /metadata-facets:
1725 get:
1726 tags: [Notes]
1727 summary: Body-free MetadataFacets hints for one note
1728 description: >
1729 Returns knowtation.metadata_facets/v0 metadata for one authorized vault-relative note.
1730 The response excludes note body text, snippets, full frontmatter, absolute paths,
1731 provider payloads, MCP resource URIs, summaries, labels, vectors, OCR, PageIndex output,
1732 media metadata, memory events, persistence records, sidecars, LLM calls, and write-back state.
1733 parameters:
1734 - name: path
1735 in: query
1736 required: true
1737 schema: { type: string }
1738 description: Vault-relative Markdown note path.
1739 responses:
1740 '200':
1741 content:
1742 application/json:
1743 schema: { $ref: '#/components/schemas/MetadataFacets' }
1744 '400':
1745 content:
1746 application/json:
1747 schema: { $ref: '#/components/schemas/Error' }
1748 '401':
1749 content:
1750 application/json:
1751 schema: { $ref: '#/components/schemas/Error' }
1752 '403':
1753 content:
1754 application/json:
1755 schema: { $ref: '#/components/schemas/Error' }
1756 '404':
1757 content:
1758 application/json:
1759 schema: { $ref: '#/components/schemas/Error' }
1760 '502':
1761 content:
1762 application/json:
1763 schema: { $ref: '#/components/schemas/Error' }
1764
1765 /section-source:
1766 get:
1767 tags: [Notes]
1768 summary: Body-free SectionSource metadata for one note
1769 description: >
1770 Returns knowtation.section_source/v0 metadata for one authorized vault-relative note.
1771 The response excludes note body text, section body text, snippets, full frontmatter,
1772 line ranges, byte offsets, section body lengths, absolute paths, raw canister payloads,
1773 provider payloads, and MCP resource URIs.
1774 parameters:
1775 - name: path
1776 in: query
1777 required: true
1778 schema: { type: string }
1779 description: Vault-relative Markdown note path.
1780 responses:
1781 '200':
1782 content:
1783 application/json:
1784 schema: { $ref: '#/components/schemas/SectionSource' }
1785 '400':
1786 content:
1787 application/json:
1788 schema: { $ref: '#/components/schemas/Error' }
1789 '401':
1790 content:
1791 application/json:
1792 schema: { $ref: '#/components/schemas/Error' }
1793 '403':
1794 content:
1795 application/json:
1796 schema: { $ref: '#/components/schemas/Error' }
1797 '404':
1798 content:
1799 application/json:
1800 schema: { $ref: '#/components/schemas/Error' }
1801 '502':
1802 content:
1803 application/json:
1804 schema: { $ref: '#/components/schemas/Error' }
1805
1806 /index:
1807 post:
1808 tags: [Notes]
1809 summary: Re-run indexer (vault to vector store)
1810 responses:
1811 '200':
1812 content:
1813 application/json:
1814 schema:
1815 type: object
1816 properties:
1817 ok: { type: boolean }
1818 notesProcessed: { type: integer }
1819 chunksIndexed: { type: integer }
1820 vectors_deleted: { type: integer, description: Rows removed for this vault before upsert (hosted sqlite-vec) }
1821 '500':
1822 content:
1823 application/json:
1824 schema: { $ref: '#/components/schemas/Error' }
1825
1826 /export:
1827 post:
1828 tags: [Notes]
1829 summary: Export one note to content (returns body + filename for client download)
1830 requestBody:
1831 required: true
1832 content:
1833 application/json:
1834 schema:
1835 type: object
1836 required: [path]
1837 properties:
1838 path: { type: string }
1839 format: { type: string, enum: [md, html] }
1840 responses:
1841 '200':
1842 content:
1843 application/json:
1844 schema:
1845 type: object
1846 properties:
1847 content: { type: string }
1848 filename: { type: string }
1849 '400':
1850 content:
1851 application/json:
1852 schema: { $ref: '#/components/schemas/Error' }
1853 '404':
1854 content:
1855 application/json:
1856 schema: { $ref: '#/components/schemas/Error' }
1857
1858 /import:
1859 post:
1860 tags: [Notes]
1861 summary: Import from uploaded file or ZIP (multipart: source_type; file except for google-sheets; optional project, tags, spreadsheet_id for google-sheets)
1862 requestBody:
1863 required: true
1864 content:
1865 multipart/form-data:
1866 schema:
1867 type: object
1868 required: [source_type]
1869 properties:
1870 source_type:
1871 type: string
1872 description: Importer id. For google-sheets, omit file and set spreadsheet_id; optional sheets_range (A1 notation). See lib/import-source-types.mjs.
1873 file: { type: string, format: binary, description: Required for all importers except google-sheets. }
1874 spreadsheet_id:
1875 type: string
1876 description: Required when source_type is google-sheets (id from the Google Sheets URL).
1877 sheets_range:
1878 type: string
1879 description: Optional for google-sheets; A1 range. Omit to read the first sheet from A1.
1880 project: { type: string }
1881 output_dir: { type: string }
1882 tags: { type: string }
1883 responses:
1884 '200':
1885 content:
1886 application/json:
1887 schema:
1888 type: object
1889 properties:
1890 imported: { type: array, items: { type: object } }
1891 count: { type: integer }
1892 '400':
1893 content:
1894 application/json:
1895 schema: { $ref: '#/components/schemas/Error' }
1896 '500':
1897 content:
1898 application/json:
1899 schema: { $ref: '#/components/schemas/Error' }
1900
1901 /import-url:
1902 post:
1903 tags: [Notes]
1904 summary: Import from a public https URL (JSON body; editor/admin)
1905 requestBody:
1906 required: true
1907 content:
1908 application/json:
1909 schema:
1910 type: object
1911 required: [url]
1912 properties:
1913 url: { type: string, description: 'Full https URL' }
1914 mode: { type: string, enum: [auto, bookmark, extract], description: 'Capture mode (default auto)' }
1915 project: { type: string }
1916 output_dir: { type: string }
1917 tags: { oneOf: [{ type: string }, { type: array, items: { type: string } }] }
1918 responses:
1919 '200':
1920 content:
1921 application/json:
1922 schema:
1923 type: object
1924 properties:
1925 imported: { type: array, items: { type: object } }
1926 count: { type: integer }
1927 '400':
1928 content:
1929 application/json:
1930 schema: { $ref: '#/components/schemas/Error' }
1931 '500':
1932 content:
1933 application/json:
1934 schema: { $ref: '#/components/schemas/Error' }
1935
1936 /settings:
1937 get:
1938 tags: [Notes]
1939 summary: Config status for Settings UI (no secrets)
1940 responses:
1941 '200':
1942 content:
1943 application/json:
1944 schema:
1945 type: object
1946 properties:
1947 vault_path_display: { type: string }
1948 vault_git:
1949 type: object
1950 properties:
1951 enabled: { type: boolean }
1952 has_remote: { type: boolean }
1953 auto_commit: { type: boolean }
1954 auto_push: { type: boolean }
1955
1956 /vault/sync:
1957 post:
1958 tags: [Notes]
1959 summary: Manual vault backup (git add, commit, push)
1960 description: Self-hosted runs local git. Hosted (bridge) pushes notes as Markdown plus `.knowtation/backup/v1/snapshot.json` with full proposals.
1961 responses:
1962 '200':
1963 content:
1964 application/json:
1965 schema:
1966 type: object
1967 properties:
1968 ok: { type: boolean }
1969 message: { type: string }
1970 notesCount: { type: integer, description: Hosted bridge only }
1971 proposalsCount: { type: integer, description: Hosted bridge only }
1972 '400':
1973 content:
1974 application/json:
1975 schema: { $ref: '#/components/schemas/Error' }
1976 '500':
1977 content:
1978 application/json:
1979 schema: { $ref: '#/components/schemas/Error' }
1980
1981 /search:
1982 post:
1983 tags: [Search]
1984 summary: Vault search (semantic or keyword)
1985 requestBody:
1986 required: true
1987 content:
1988 application/json:
1989 schema:
1990 type: object
1991 required: [query]
1992 properties:
1993 query: { type: string }
1994 mode: { type: string, enum: [semantic, keyword], description: Omitted or semantic = vector search; keyword = substring/token match on note text }
1995 match: { type: string, enum: [phrase, all_terms], description: Keyword only; phrase = full query substring; all_terms = every token must appear }
1996 folder: { type: string }
1997 project: { type: string }
1998 tag: { type: string }
1999 since: { type: string }
2000 until: { type: string }
2001 chain: { type: string }
2002 entity: { type: string }
2003 episode: { type: string }
2004 limit: { type: integer }
2005 order: { type: string }
2006 fields: { type: string }
2007 content_scope: { type: string, enum: [notes, approval_logs], description: Narrow to normal notes vs approvals/ logs }
2008 snippetChars: { type: integer }
2009 count_only: { type: boolean }
2010 countOnly: { type: boolean }
2011 responses:
2012 '200':
2013 content:
2014 application/json:
2015 schema:
2016 type: object
2017 properties:
2018 results: { type: array, items: { $ref: '#/components/schemas/SearchResult' } }
2019 query: { type: string }
2020 mode: { type: string, enum: [semantic, keyword] }
2021 count: { type: integer, description: Present when count_only keyword search }
2022 '400':
2023 content:
2024 application/json:
2025 schema: { $ref: '#/components/schemas/Error' }
2026
2027 /proposals:
2028 get:
2029 tags: [Proposals]
2030 summary: List proposals
2031 parameters:
2032 - name: status
2033 in: query
2034 schema: { type: string }
2035 - name: limit
2036 in: query
2037 schema: { type: integer }
2038 - name: offset
2039 in: query
2040 schema: { type: integer }
2041 - name: label
2042 in: query
2043 description: Match if proposal labels include this string (case-insensitive)
2044 schema: { type: string }
2045 - name: source
2046 in: query
2047 schema: { type: string }
2048 - name: path_prefix
2049 in: query
2050 schema: { type: string }
2051 - name: evaluation_status
2052 in: query
2053 description: Filter by evaluation_status (none, pending, passed, failed, needs_changes)
2054 schema: { type: string }
2055 - name: review_queue
2056 in: query
2057 description: Exact match on proposal review_queue
2058 schema: { type: string }
2059 - name: review_severity
2060 in: query
2061 description: standard or elevated
2062 schema: { type: string }
2063 responses:
2064 '200':
2065 content:
2066 application/json:
2067 schema:
2068 type: object
2069 properties:
2070 proposals: { type: array, items: { $ref: '#/components/schemas/Proposal' } }
2071 total: { type: integer }
2072 post:
2073 tags: [Proposals]
2074 summary: Create proposal
2075 requestBody:
2076 content:
2077 application/json:
2078 schema:
2079 type: object
2080 properties:
2081 path: { type: string }
2082 body: { type: string }
2083 frontmatter: { type: object }
2084 intent: { type: string }
2085 base_state_id: { type: string }
2086 external_ref: { type: string }
2087 labels: { type: array, items: { type: string } }
2088 source: { type: string }
2089 responses:
2090 '201':
2091 content:
2092 application/json:
2093 schema:
2094 type: object
2095 properties:
2096 proposal_id: { type: string }
2097 path: { type: string }
2098 status: { type: string, enum: [proposed] }
2099 '400':
2100
2101 /proposals/{id}:
2102 get:
2103 tags: [Proposals]
2104 summary: Get one proposal
2105 parameters:
2106 - name: id
2107 in: path
2108 required: true
2109 schema: { type: string }
2110 responses:
2111 '200':
2112 content:
2113 application/json:
2114 schema: { $ref: '#/components/schemas/ProposalDetail' }
2115 '404':
2116
2117 /proposals/{id}/review-hints:
2118 post:
2119 tags: [Proposals]
2120 summary: Store async LLM review hints (canister; not a merge gate)
2121 parameters:
2122 - name: id
2123 in: path
2124 required: true
2125 schema: { type: string }
2126 requestBody:
2127 content:
2128 application/json:
2129 schema:
2130 type: object
2131 properties:
2132 review_hints: { type: string }
2133 review_hints_model: { type: string }
2134 responses:
2135 '200':
2136 content:
2137 application/json:
2138 schema:
2139 type: object
2140 properties:
2141 proposal_id: { type: string }
2142 ok: { type: boolean }
2143
2144 /proposals/{id}/evaluation:
2145 post:
2146 tags: [Proposals]
2147 summary: Submit human evaluation (admin or evaluator)
2148 parameters:
2149 - name: id
2150 in: path
2151 required: true
2152 schema: { type: string }
2153 requestBody:
2154 content:
2155 application/json:
2156 schema:
2157 type: object
2158 required: [outcome]
2159 properties:
2160 outcome:
2161 type: string
2162 enum: [pass, fail, needs_changes]
2163 checklist:
2164 type: array
2165 items:
2166 type: object
2167 properties:
2168 id: { type: string }
2169 passed: { type: boolean }
2170 grade: { type: string }
2171 comment: { type: string }
2172 responses:
2173 '200':
2174 content:
2175 application/json:
2176 schema: { $ref: '#/components/schemas/ProposalDetail' }
2177 '400':
2178 '404':
2179
2180 /proposals/{id}/approve:
2181 post:
2182 tags: [Proposals]
2183 summary: Apply proposal to vault
2184 parameters:
2185 - name: id
2186 in: path
2187 required: true
2188 schema: { type: string }
2189 requestBody:
2190 content:
2191 application/json:
2192 schema:
2193 type: object
2194 properties:
2195 base_state_id: { type: string }
2196 waiver_reason:
2197 type: string
2198 description: Admin override when evaluation is not passed (min length 3 after trim)
2199 external_ref:
2200 type: string
2201 description: Optional cross-system lineage id (e.g. Muse); server may resolve via MUSE_URL when omitted
2202 responses:
2203 '200':
2204 content:
2205 application/json:
2206 schema:
2207 type: object
2208 properties:
2209 proposal_id: { type: string }
2210 status: { type: string, enum: [approved] }
2211 external_ref: { type: string }
2212 '403':
2213 description: EVALUATION_REQUIRED — pass evaluation or provide waiver_reason
2214 '409':
2215 description: base_state_id mismatch (CONFLICT)
2216
2217 /proposals/{id}/enrich:
2218 post:
2219 tags: [Proposals]
2220 summary: Optional LLM summary and suggested labels (KNOWTATION_HUB_PROPOSAL_ENRICH=1)
2221 parameters:
2222 - name: id
2223 in: path
2224 required: true
2225 schema: { type: string }
2226 responses:
2227 '200':
2228 content:
2229 application/json:
2230 schema: { $ref: '#/components/schemas/ProposalDetail' }
2231 '400':
2232 description: >-
2233 ICP canister — suggested_labels_json or assistant_suggested_frontmatter_json is valid JSON
2234 but exceeds max length (4000 / 14000 characters) after validation.
2235 '404':
2236
2237 /proposals/{id}/discard:
2238 post:
2239 tags: [Proposals]
2240 summary: Discard proposal
2241 parameters:
2242 - name: id
2243 in: path
2244 required: true
2245 schema: { type: string }
2246 responses:
2247 '200':
2248 content:
2249 application/json:
2250 schema:
2251 type: object
2252 properties:
2253 proposal_id: { type: string }
2254 status: { type: string, enum: [discarded] }
2255
2256 /capture:
2257 post:
2258 tags: [Capture]
2259 summary: Ingest message into vault inbox (webhook-style)
2260 description: Same contract as capture-webhook. If CAPTURE_WEBHOOK_SECRET is set, require X-Webhook-Secret header.
2261 security: []
2262 requestBody:
2263 content:
2264 application/json:
2265 schema:
2266 type: object
2267 required: [body]
2268 properties:
2269 body: { type: string }
2270 source_id: { type: string }
2271 source: { type: string }
2272 project: { type: string }
2273 tags: { type: array, items: { type: string } }
2274 responses:
2275 '200':
2276 content:
2277 application/json:
2278 schema: { type: object, properties: { ok: { type: boolean }, path: { type: string } } }
2279 '400':
2280
2281 components:
2282 securitySchemes:
2283 BearerAuth:
2284 type: http
2285 scheme: bearer
2286 bearerFormat: JWT
2287
2288 schemas:
2289 Error:
2290 type: object
2291 properties:
2292 error: { type: string }
2293 code: { type: string }
2294
2295 NoteListItem:
2296 type: object
2297 properties:
2298 path: { type: string }
2299 title: { type: string, nullable: true }
2300 project: { type: string, nullable: true }
2301 tags: { type: array, items: { type: string } }
2302 date: { type: string, nullable: true }
2303
2304 NoteFull:
2305 type: object
2306 properties:
2307 path: { type: string }
2308 frontmatter: { type: object }
2309 body: { type: string }
2310
2311 SearchResult:
2312 type: object
2313 properties:
2314 path: { type: string }
2315 snippet: { type: string }
2316 score: { type: number }
2317 project: { type: string }
2318 tags: { type: array, items: { type: string } }
2319
2320 NoteOutline:
2321 type: object
2322 required: [schema, path, headings, truncated]
2323 properties:
2324 schema:
2325 type: string
2326 enum: [knowtation.note_outline/v1]
2327 path: { type: string }
2328 title: { type: string, nullable: true }
2329 headings:
2330 type: array
2331 maxItems: 500
2332 items: { $ref: '#/components/schemas/NoteOutlineHeading' }
2333 truncated: { type: boolean }
2334
2335 NoteOutlineHeading:
2336 type: object
2337 required: [level, text, id]
2338 properties:
2339 level: { type: integer, minimum: 1, maximum: 6 }
2340 text: { type: string }
2341 id: { type: string }
2342
2343 DocumentTree:
2344 type: object
2345 required: [schema, path, root, truncated]
2346 properties:
2347 schema:
2348 type: string
2349 enum: [knowtation.document_tree/v0]
2350 path: { type: string }
2351 title: { type: string, nullable: true }
2352 root:
2353 type: object
2354 required: [children]
2355 properties:
2356 children:
2357 type: array
2358 maxItems: 500
2359 items: { $ref: '#/components/schemas/DocumentTreeNode' }
2360 truncated: { type: boolean }
2361
2362 DocumentTreeNode:
2363 type: object
2364 required: [id, level, text, children]
2365 properties:
2366 id: { type: string }
2367 level: { type: integer, minimum: 1, maximum: 6 }
2368 text: { type: string }
2369 children:
2370 type: array
2371 items: { $ref: '#/components/schemas/DocumentTreeNode' }
2372
2373 MetadataFacets:
2374 type: object
2375 required: [schema, path, facets, inferred, truncated]
2376 properties:
2377 schema:
2378 type: string
2379 enum: [knowtation.metadata_facets/v0]
2380 path: { type: string }
2381 facets:
2382 type: object
2383 required: [project, tags, date, updated, causal_chain_id, entity, episode_id]
2384 properties:
2385 project: { type: string, nullable: true }
2386 tags:
2387 type: array
2388 maxItems: 100
2389 items: { type: string }
2390 date: { type: string, nullable: true }
2391 updated: { type: string, nullable: true }
2392 causal_chain_id: { type: string, nullable: true }
2393 entity:
2394 type: array
2395 maxItems: 100
2396 items: { type: string }
2397 episode_id: { type: string, nullable: true }
2398 inferred:
2399 type: object
2400 required: [folder, source_type]
2401 properties:
2402 folder: { type: string, nullable: true }
2403 source_type: { nullable: true, enum: [null] }
2404 truncated: { type: boolean }
2405
2406 SectionSource:
2407 type: object
2408 required: [schema, path, sections, truncated]
2409 properties:
2410 schema:
2411 type: string
2412 enum: [knowtation.section_source/v0]
2413 path: { type: string }
2414 title: { type: string, nullable: true }
2415 sections:
2416 type: array
2417 items: { $ref: '#/components/schemas/SectionSourceSection' }
2418 truncated: { type: boolean }
2419
2420 SectionSourceSection:
2421 type: object
2422 required:
2423 - section_id
2424 - heading_id
2425 - level
2426 - heading_path
2427 - heading_text
2428 - child_section_ids
2429 - body_available
2430 - body_returned
2431 - snippet_returned
2432 properties:
2433 section_id: { type: string }
2434 heading_id: { type: string }
2435 level: { type: integer, minimum: 1, maximum: 6 }
2436 heading_path: { type: array, items: { type: string } }
2437 heading_text: { type: string }
2438 child_section_ids: { type: array, items: { type: string } }
2439 body_available: { type: boolean }
2440 body_returned: { type: boolean, enum: [false] }
2441 snippet_returned: { type: boolean, enum: [false] }
2442
2443 Proposal:
2444 type: object
2445 properties:
2446 proposal_id: { type: string }
2447 path: { type: string }
2448 status: { type: string }
2449 intent: { type: string }
2450 base_state_id: { type: string }
2451 external_ref: { type: string }
2452 vault_id: { type: string }
2453 proposed_by: { type: string }
2454 labels: { type: array, items: { type: string } }
2455 source: { type: string }
2456 suggested_labels: { type: array, items: { type: string } }
2457 assistant_notes: { type: string }
2458 assistant_model: { type: string }
2459 assistant_at: { type: string }
2460 created_at: { type: string }
2461 updated_at: { type: string }
2462 evaluation_status:
2463 type: string
2464 enum: [none, pending, passed, failed, needs_changes]
2465 evaluation_grade: { type: string }
2466 evaluation_comment: { type: string }
2467 evaluated_by: { type: string }
2468 evaluated_at: { type: string }
2469 evaluation_waiver:
2470 type: object
2471 nullable: true
2472 properties:
2473 by: { type: string }
2474 at: { type: string }
2475 reason: { type: string }
2476 review_queue: { type: string }
2477 review_severity: { type: string, enum: [standard, elevated] }
2478 auto_flag_reasons:
2479 type: array
2480 items: { type: string }
2481 auto_flag_reasons_json: { type: string, description: JSON array string on canister }
2482 review_hints: { type: string }
2483 review_hints_at: { type: string }
2484 review_hints_model: { type: string }
2485 assistant_suggested_frontmatter:
2486 type: object
2487 description: Normalized SPEC-aligned suggested note metadata from Enrich (object on GET); omitted or empty on older proposals
2488 additionalProperties: true
2489
2490 ProposalDetail:
2491 allOf:
2492 - { $ref: '#/components/schemas/Proposal' }
2493 - type: object
2494 properties:
2495 body: { type: string }
2496 frontmatter: { type: object }
2497 evaluation_checklist:
2498 type: array
2499 items:
2500 type: object
2501 properties:
2502 id: { type: string }
2503 label: { type: string }
2504 passed: { type: boolean }
2505
2506 CalendarTimeline:
2507 type: object
2508 required: [schema, vault_id, from, to, layers, items]
2509 properties:
2510 schema:
2511 type: string
2512 enum: [knowtation.calendar_timeline/v0]
2513 vault_id: { type: string }
2514 from: { type: string }
2515 to: { type: string }
2516 layers:
2517 type: array
2518 items:
2519 type: string
2520 enum: [notes, events]
2521 items:
2522 type: array
2523 items:
2524 oneOf:
2525 - { $ref: '#/components/schemas/CalendarTimelineNoteItem' }
2526 - { $ref: '#/components/schemas/CalendarTimelineEventItem' }
2527
2528 CalendarTimelineNoteItem:
2529 type: object
2530 required: [kind, date, path, title, project, tags, sort_at]
2531 properties:
2532 kind:
2533 type: string
2534 enum: [note]
2535 date: { type: string }
2536 path: { type: string }
2537 title: { type: string, nullable: true }
2538 project: { type: string, nullable: true }
2539 tags:
2540 type: array
2541 items: { type: string }
2542 sort_at: { type: string }
2543
2544 CalendarTimelineEventItem:
2545 type: object
2546 required: [kind, event_id, source_calendar_id, start, end, timezone, summary, busy, status, calendar_label, sort_at]
2547 properties:
2548 kind:
2549 type: string
2550 enum: [event]
2551 event_id: { type: string }
2552 source_calendar_id: { type: string }
2553 start: { type: string }
2554 end: { type: string }
2555 timezone: { type: string }
2556 summary: { type: string, nullable: true }
2557 busy: { type: boolean }
2558 status:
2559 type: string
2560 enum: [confirmed, cancelled, tentative]
2561 calendar_label: { type: string, nullable: true }
2562 sort_at: { type: string }
2563
2564 CalendarAgentContext:
2565 type: object
2566 required: [schema, vault_id, from, to, requested_tier, effective_tier, policy_agent_context_tier_max_cap, source_calendars, items]
2567 properties:
2568 schema:
2569 type: string
2570 enum: [knowtation.calendar_agent_context/v0]
2571 vault_id: { type: string }
2572 from: { type: string }
2573 to: { type: string }
2574 requested_tier:
2575 type: integer
2576 minimum: 0
2577 maximum: 2
2578 effective_tier:
2579 type: integer
2580 minimum: 0
2581 maximum: 2
2582 description: Requested tier after the org policy cap is applied.
2583 policy_agent_context_tier_max_cap:
2584 type: integer
2585 minimum: 0
2586 maximum: 4
2587 source_calendars:
2588 type: array
2589 items: { $ref: '#/components/schemas/AgentContextCalendarSummary' }
2590 items:
2591 type: array
2592 items: { $ref: '#/components/schemas/CalendarAgentContextEventItem' }
2593
2594 AgentContextCalendarSummary:
2595 type: object
2596 required: [source_calendar_id, display_name, user_group, enabled_for_agents, agent_context_tier_max, effective_tier, event_count]
2597 properties:
2598 source_calendar_id: { type: string }
2599 display_name: { type: string }
2600 user_group:
2601 type: string
2602 nullable: true
2603 enum: [personal, work, school, other, null]
2604 enabled_for_agents: { type: boolean }
2605 agent_context_tier_max:
2606 type: integer
2607 minimum: 0
2608 maximum: 4
2609 effective_tier:
2610 type: integer
2611 minimum: 0
2612 maximum: 2
2613 event_count: { type: integer }
2614
2615 CalendarAgentContextEventItem:
2616 type: object
2617 required: [event_id, source_calendar_id, external_uid, start, end, timezone, busy, status, agent_tier]
2618 description: >
2619 Redacted event. `summary` and `calendar_label` are present only at tier 2;
2620 tier 1 omits the event title entirely.
2621 properties:
2622 event_id: { type: string }
2623 source_calendar_id: { type: string }
2624 external_uid: { type: string }
2625 start: { type: string }
2626 end: { type: string }
2627 timezone: { type: string }
2628 busy: { type: boolean }
2629 status:
2630 type: string
2631 enum: [confirmed, cancelled, tentative]
2632 agent_tier:
2633 type: integer
2634 minimum: 1
2635 maximum: 2
2636 summary: { type: string, nullable: true }
2637 calendar_label: { type: string, nullable: true }
2638
2639 SourceCalendarList:
2640 type: object
2641 required: [schema, vault_id, source_calendars]
2642 properties:
2643 schema:
2644 type: string
2645 enum: [knowtation.source_calendars/v0]
2646 vault_id: { type: string }
2647 source_calendars:
2648 type: array
2649 items: { $ref: '#/components/schemas/SourceCalendar' }
2650
2651 SourceCalendar:
2652 type: object
2653 required: [source_calendar_id, connector_id, display_name, enabled_for_sync, enabled_for_display, enabled_for_agents, agent_context_tier_max]
2654 properties:
2655 source_calendar_id: { type: string }
2656 connector_id: { type: string }
2657 display_name: { type: string }
2658 color: { type: string, nullable: true }
2659 user_group:
2660 type: string
2661 nullable: true
2662 enum: [personal, work, school, other, null]
2663 enabled_for_sync: { type: boolean }
2664 enabled_for_display: { type: boolean }
2665 enabled_for_agents: { type: boolean }
2666 agent_context_tier_max:
2667 type: integer
2668 minimum: 0
2669 maximum: 4
2670 provider: { type: string }
2671
2672 CalendarIcsImportRequest:
2673 type: object
2674 required: [ics_text]
2675 properties:
2676 ics_text: { type: string }
2677 display_name: { type: string }
2678 source_calendar_id: { type: string }
2679 connector_id: { type: string }
2680 default_timezone: { type: string }
2681
2682 CalendarIcsImportResult:
2683 type: object
2684 required: [schema, vault_id, source_calendar_id, connector_id, imported, updated]
2685 properties:
2686 schema:
2687 type: string
2688 enum: [knowtation.calendar_import/v0]
2689 vault_id: { type: string }
2690 source_calendar_id: { type: string }
2691 connector_id: { type: string }
2692 imported: { type: integer }
2693 updated: { type: integer }
2694
2695 SourceCalendarPatchRequest:
2696 type: object
2697 minProperties: 1
2698 properties:
2699 enabled_for_display: { type: boolean }
2700 enabled_for_agents: { type: boolean }
2701 agent_context_tier_max:
2702 type: integer
2703 minimum: 0
2704 maximum: 4
2705 user_group:
2706 type: string
2707 nullable: true
2708 enum: [personal, work, school, other, null]
2709
2710 SourceCalendarPatchResult:
2711 type: object
2712 required: [schema, vault_id, policy_agent_context_tier_max_cap, source_calendar]
2713 properties:
2714 schema:
2715 type: string
2716 enum: [knowtation.source_calendar_patch/v0]
2717 vault_id: { type: string }
2718 policy_agent_context_tier_max_cap:
2719 type: integer
2720 minimum: 0
2721 maximum: 4
2722 source_calendar: { $ref: '#/components/schemas/SourceCalendar' }
2723
2724 FlowListResponse:
2725 type: object
2726 required: [schema, vault_id, effective_scope, flows, truncated]
2727 properties:
2728 schema:
2729 type: string
2730 enum: [knowtation.flow_list/v0]
2731 vault_id: { type: string }
2732 effective_scope:
2733 type: string
2734 enum: [personal, project, org]
2735 flows:
2736 type: array
2737 maxItems: 200
2738 items: { $ref: '#/components/schemas/FlowSummary' }
2739 truncated: { type: boolean }
2740
2741 TaskListResponse:
2742 type: object
2743 required: [schema, vault_id, effective_scope, tasks, truncated]
2744 properties:
2745 schema:
2746 type: string
2747 enum: [knowtation.task_list/v0]
2748 vault_id: { type: string }
2749 effective_scope:
2750 type: string
2751 enum: [personal, project, org]
2752 tasks:
2753 type: array
2754 maxItems: 500
2755 items: { $ref: '#/components/schemas/TaskSummary' }
2756 truncated: { type: boolean }
2757
2758 TaskSummary:
2759 type: object
2760 required: [schema, task_id, kind, scope, status, title, workspace_id, due_at, run_ref, truncated]
2761 properties:
2762 schema:
2763 type: string
2764 enum: [knowtation.task/v0]
2765 task_id: { type: string }
2766 kind:
2767 type: string
2768 enum: [personal, assignment, mentor_checkin, org_work_job]
2769 scope:
2770 type: string
2771 enum: [personal, project, org]
2772 status:
2773 type: string
2774 enum: [pending, in_progress, blocked, done, cancelled]
2775 title: { type: string }
2776 workspace_id: { type: string }
2777 due_at:
2778 type: string
2779 nullable: true
2780 run_ref:
2781 type: string
2782 nullable: true
2783 truncated: { type: boolean }
2784
2785 TaskGetResponse:
2786 type: object
2787 required: [schema, vault_id, effective_scope, task]
2788 properties:
2789 schema:
2790 type: string
2791 enum: [knowtation.task_get/v0]
2792 vault_id: { type: string }
2793 effective_scope:
2794 type: string
2795 enum: [personal, project, org]
2796 task: { $ref: '#/components/schemas/TaskRecord' }
2797
2798 TaskRecord:
2799 type: object
2800 required:
2801 - schema
2802 - task_id
2803 - kind
2804 - scope
2805 - status
2806 - title
2807 - workspace_id
2808 - due_at
2809 - artifact_links
2810 - created
2811 - updated
2812 - truncated
2813 properties:
2814 schema:
2815 type: string
2816 enum: [knowtation.task/v0]
2817 task_id: { type: string }
2818 kind:
2819 type: string
2820 enum: [personal, assignment, mentor_checkin, org_work_job]
2821 scope:
2822 type: string
2823 enum: [personal, project, org]
2824 status:
2825 type: string
2826 enum: [pending, in_progress, blocked, done, cancelled]
2827 title: { type: string }
2828 workspace_id: { type: string }
2829 due_at:
2830 type: string
2831 nullable: true
2832 assignee_ref:
2833 type: string
2834 nullable: true
2835 assigner_ref:
2836 type: string
2837 nullable: true
2838 run_ref:
2839 type: string
2840 nullable: true
2841 artifact_links:
2842 type: array
2843 maxItems: 32
2844 items:
2845 type: object
2846 required: [kind, ref]
2847 properties:
2848 kind:
2849 type: string
2850 enum: [note, media, review_item]
2851 ref: { type: string }
2852 created: { type: string }
2853 updated: { type: string }
2854 truncated: { type: boolean }
2855
2856 AttachmentListResponse:
2857 type: object
2858 required: [schema, vault_id, effective_scope, attachments, truncated]
2859 properties:
2860 schema:
2861 type: string
2862 enum: [knowtation.attachment_list/v0]
2863 vault_id: { type: string }
2864 effective_scope:
2865 type: string
2866 enum: [personal, project, org]
2867 attachments:
2868 type: array
2869 maxItems: 500
2870 items: { $ref: '#/components/schemas/AttachmentSummary' }
2871 truncated: { type: boolean }
2872
2873 AttachmentSummary:
2874 type: object
2875 required:
2876 - schema
2877 - attachment_id
2878 - source
2879 - storage_kind
2880 - mime_class
2881 - scope
2882 - display_label
2883 - created
2884 - truncated
2885 properties:
2886 schema:
2887 type: string
2888 enum: [knowtation.attachment/v0]
2889 attachment_id: { type: string }
2890 source:
2891 type: string
2892 enum: [vault_file, mist_blob, embedded_url]
2893 storage_kind:
2894 type: string
2895 enum: [vault_blob, external_link]
2896 mime_class:
2897 type: string
2898 enum: [image, video, audio, document, unknown]
2899 scope:
2900 type: string
2901 enum: [personal, project, org]
2902 display_label: { type: string }
2903 created: { type: string }
2904 truncated: { type: boolean }
2905
2906 AttachmentGetResponse:
2907 type: object
2908 required: [schema, vault_id, effective_scope, attachment]
2909 properties:
2910 schema:
2911 type: string
2912 enum: [knowtation.attachment_get/v0]
2913 vault_id: { type: string }
2914 effective_scope:
2915 type: string
2916 enum: [personal, project, org]
2917 attachment: { $ref: '#/components/schemas/AttachmentRecord' }
2918
2919 MediaProposalResponse:
2920 type: object
2921 required: [schema, proposal_id, proposal_kind, attachment_id, scope, auto_approvable, status]
2922 properties:
2923 schema:
2924 type: string
2925 enum: [knowtation.media_proposal/v0]
2926 proposal_id: { type: string }
2927 proposal_kind:
2928 type: string
2929 enum: [media_external_link, media_attach]
2930 attachment_id:
2931 type: string
2932 pattern: '^att_(file|mist|url|link)_[a-f0-9]{32}$'
2933 note_ref: { type: [string, 'null'] }
2934 connector_id: { type: [string, 'null'] }
2935 scope:
2936 type: string
2937 enum: [personal, project, org]
2938 base_state_id: { type: string }
2939 external_ref: { type: [string, 'null'] }
2940 auto_approvable:
2941 type: boolean
2942 enum: [false]
2943 status:
2944 type: string
2945 enum: [proposed]
2946 review_queue:
2947 type: string
2948 enum: [media-writes]
2949
2950 AttachmentRecord:
2951 type: object
2952 required:
2953 - schema
2954 - attachment_id
2955 - source
2956 - storage_kind
2957 - mime_class
2958 - mime_type
2959 - scope
2960 - display_label
2961 - byte_size
2962 - linked_note_refs
2963 - agent_visible
2964 - created
2965 - updated
2966 - truncated
2967 properties:
2968 schema:
2969 type: string
2970 enum: [knowtation.attachment/v0]
2971 attachment_id: { type: string }
2972 source:
2973 type: string
2974 enum: [vault_file, mist_blob, embedded_url]
2975 storage_kind:
2976 type: string
2977 enum: [vault_blob, external_link]
2978 mime_class:
2979 type: string
2980 enum: [image, video, audio, document, unknown]
2981 mime_type:
2982 type: string
2983 nullable: true
2984 scope:
2985 type: string
2986 enum: [personal, project, org]
2987 display_label: { type: string }
2988 byte_size:
2989 type: integer
2990 nullable: true
2991 linked_note_refs:
2992 type: array
2993 items: { type: string }
2994 agent_visible: { type: boolean }
2995 created: { type: string }
2996 updated: { type: string }
2997 truncated: { type: boolean }
2998
2999 TaskWriteProposalRequest:
3000 type: object
3001 required: [intent]
3002 properties:
3003 proposal_kind:
3004 type: string
3005 enum: [task_create, task_status_update, task_assign, task_artifact_link]
3006 intent: { type: string, minLength: 1 }
3007 task: { $ref: '#/components/schemas/TaskRecord' }
3008 task_id: { type: string }
3009 base_state_id: { type: string }
3010 status:
3011 type: string
3012 enum: [pending, in_progress, blocked, done, cancelled]
3013 assignee_ref: { type: string, nullable: true }
3014 assigner_ref: { type: string, nullable: true }
3015 artifact_link:
3016 type: object
3017 required: [kind, ref]
3018 properties:
3019 kind: { type: string }
3020 ref: { type: string }
3021
3022 TaskLoopWriteProposalRequest:
3023 type: object
3024 required: [intent]
3025 properties:
3026 proposal_kind:
3027 type: string
3028 enum: [task_loop_create, task_loop_pause, task_loop_cancel]
3029 intent: { type: string, minLength: 1 }
3030 loop: { type: object }
3031 loop_id: { type: string }
3032 base_state_id: { type: string }
3033
3034 TaskInstanceMaterializeRequest:
3035 type: object
3036 required: [intent]
3037 properties:
3038 intent: { type: string, minLength: 1 }
3039 occurrence_key: { type: string }
3040 occurrence_at: { type: string }
3041 due_at: { type: string }
3042 title_override: { type: string }
3043 base_state_id: { type: string }
3044
3045 TaskProposalResponse:
3046 type: object
3047 required:
3048 - schema
3049 - proposal_id
3050 - proposal_kind
3051 - auto_approvable
3052 - status
3053 - review_queue
3054 properties:
3055 schema:
3056 type: string
3057 enum: [knowtation.task_proposal/v0]
3058 proposal_id: { type: string }
3059 proposal_kind: { type: string }
3060 task_id: { type: string, nullable: true }
3061 loop_id: { type: string, nullable: true }
3062 base_state_id: { type: string, nullable: true }
3063 scope:
3064 type: string
3065 enum: [personal, project, org]
3066 auto_approvable: { type: boolean }
3067 status: { type: string }
3068 review_queue: { type: string }
3069
3070 TaskInstanceProposalResponse:
3071 allOf:
3072 - $ref: '#/components/schemas/TaskProposalResponse'
3073 - type: object
3074 required: [occurrence_key]
3075 properties:
3076 schema:
3077 type: string
3078 enum: [knowtation.task_instance_proposal/v0]
3079 occurrence_key: { type: string }
3080
3081 FlowSummary:
3082 type: object
3083 required: [schema, flow_id, title, version, scope, summary, tags, step_count, updated, truncated]
3084 properties:
3085 schema:
3086 type: string
3087 enum: [knowtation.flow/v0]
3088 flow_id: { type: string }
3089 title: { type: string }
3090 version: { type: string }
3091 scope:
3092 type: string
3093 enum: [personal, project, org]
3094 summary: { type: string }
3095 tags:
3096 type: array
3097 maxItems: 32
3098 items: { type: string }
3099 step_count: { type: integer, minimum: 0 }
3100 updated: { type: string }
3101 truncated: { type: boolean }
3102
3103 FlowGetResponse:
3104 type: object
3105 required: [schema, vault_id, flow, steps]
3106 properties:
3107 schema:
3108 type: string
3109 enum: [knowtation.flow_get/v0]
3110 vault_id: { type: string }
3111 flow: { $ref: '#/components/schemas/Flow' }
3112 steps:
3113 type: array
3114 maxItems: 100
3115 items: { $ref: '#/components/schemas/FlowStep' }
3116
3117 FlowRun:
3118 type: object
3119 required:
3120 [schema, run_id, run_ref, flow_id, flow_version, scope, status, step_states, started, provenance]
3121 description: knowtation.flow_run/v0 — canonical run state (pointer-only).
3122 properties:
3123 schema:
3124 type: string
3125 enum: [knowtation.flow_run/v0]
3126 run_id: { type: string }
3127 run_ref:
3128 type: string
3129 description: Portable cross-system pointer (flow_run:…); resolves get/list lookups.
3130 flow_id: { type: string }
3131 flow_version: { type: string }
3132 scope:
3133 type: string
3134 enum: [personal, project, org]
3135 status:
3136 type: string
3137 enum: [pending, in_progress, blocked, done, abandoned]
3138 step_states:
3139 type: array
3140 maxItems: 200
3141 items:
3142 type: object
3143 required: [step_id, status, verified]
3144 properties:
3145 step_id: { type: string }
3146 status:
3147 type: string
3148 enum: [pending, in_progress, blocked, done, skipped]
3149 evidence_ref: { type: string, nullable: true }
3150 verified: { type: boolean }
3151 started: { type: string, format: date-time }
3152 provenance:
3153 type: object
3154 required: [actor, harness]
3155 properties:
3156 actor: { type: string, description: Hashed actor id only }
3157 harness: { type: string }
3158 task_ref: { type: string, nullable: true }
3159 external_ref: { type: string, nullable: true }
3160
3161 FlowRunGetResponse:
3162 type: object
3163 required: [schema, vault_id, run]
3164 properties:
3165 schema:
3166 type: string
3167 enum: [knowtation.flow_run_get/v0]
3168 vault_id: { type: string }
3169 run: { $ref: '#/components/schemas/FlowRun' }
3170
3171 FlowRunResponse:
3172 allOf:
3173 - $ref: '#/components/schemas/FlowRunGetResponse'
3174
3175 FlowRunListResponse:
3176 type: object
3177 required: [schema, vault_id, effective_scope, runs, truncated]
3178 properties:
3179 schema:
3180 type: string
3181 enum: [knowtation.flow_run_list/v0]
3182 vault_id: { type: string }
3183 effective_scope:
3184 type: string
3185 enum: [personal, project, org]
3186 runs:
3187 type: array
3188 maxItems: 200
3189 items: { $ref: '#/components/schemas/FlowRun' }
3190 truncated: { type: boolean }
3191
3192 FlowRunStartResponse:
3193 type: object
3194 required: [schema, run]
3195 properties:
3196 schema:
3197 type: string
3198 enum: [knowtation.flow_run_start/v0]
3199 run: { $ref: '#/components/schemas/FlowRun' }
3200
3201 FlowRunSubmitReviewResponse:
3202 type: object
3203 required: [schema, run, proposal_id]
3204 properties:
3205 schema:
3206 type: string
3207 enum: [knowtation.flow_run_submit_review/v0]
3208 run: { $ref: '#/components/schemas/FlowRun' }
3209 proposal_id: { type: string }
3210
3211 FlowProposeRequest:
3212 type: object
3213 required: [flow, steps, intent]
3214 description: Propose a new Flow. intent is untrusted and recorded verbatim.
3215 properties:
3216 flow: { $ref: '#/components/schemas/Flow' }
3217 steps:
3218 type: array
3219 maxItems: 100
3220 items: { $ref: '#/components/schemas/FlowStep' }
3221 intent: { type: string, minLength: 1 }
3222
3223 FlowProposeEditRequest:
3224 type: object
3225 required: [flow, steps, intent, base_version, base_state_id]
3226 description: >
3227 Propose an edit. base_version + base_state_id (flowst1_ token) gate
3228 optimistic concurrency; flow.version must exceed base_version.
3229 properties:
3230 flow: { $ref: '#/components/schemas/Flow' }
3231 steps:
3232 type: array
3233 maxItems: 100
3234 items: { $ref: '#/components/schemas/FlowStep' }
3235 intent: { type: string, minLength: 1 }
3236 base_version: { type: string }
3237 base_state_id: { type: string }
3238
3239 FlowImportRequest:
3240 type: object
3241 required: [bundle, intent]
3242 description: Import a portable bundle through the same scope-checked propose path.
3243 properties:
3244 bundle:
3245 type: object
3246 required: [flow, steps]
3247 properties:
3248 flow: { $ref: '#/components/schemas/Flow' }
3249 steps:
3250 type: array
3251 maxItems: 100
3252 items: { $ref: '#/components/schemas/FlowStep' }
3253 intent: { type: string, minLength: 1 }
3254 external_ref: { type: string }
3255 source_vault_hint: { type: string }
3256
3257 FlowProposalResponse:
3258 type: object
3259 required: [schema, proposal_id, flow_id, scope, auto_approvable, status, review_queue]
3260 description: >
3261 knowtation.flow_proposal/v0 envelope — pointers/labels only, never a
3262 rendered Flow body or secret. base_version/base_state_id are null for new.
3263 properties:
3264 schema:
3265 type: string
3266 enum: [knowtation.flow_proposal/v0]
3267 proposal_id: { type: string }
3268 flow_id: { type: string }
3269 base_version: { type: string, nullable: true }
3270 base_state_id: { type: string, nullable: true }
3271 scope:
3272 type: string
3273 enum: [personal, project, org]
3274 auto_approvable: { type: boolean }
3275 status:
3276 type: string
3277 enum: [proposed]
3278 review_queue: { type: string }
3279
3280 FlowExternalGrantMintRequest:
3281 type: object
3282 required: [flow_version, requested_tools]
3283 properties:
3284 flow_version: { type: string }
3285 requested_tools:
3286 type: array
3287 minItems: 1
3288 items: { type: string }
3289 ttl_seconds: { type: integer, minimum: 1 }
3290 actor_label: { type: string }
3291
3292 FlowExternalGrant:
3293 type: object
3294 required:
3295 - schema
3296 - grant_id
3297 - vault_id
3298 - scope
3299 - flow_id
3300 - flow_version
3301 - allowed_tools
3302 - allowed_harnesses
3303 - expires_at
3304 - issued_at
3305 - revoked_at
3306 - actor_hash
3307 - invocation_count
3308 properties:
3309 schema:
3310 type: string
3311 enum: [knowtation.flow_external_grant/v0]
3312 grant_id: { type: string }
3313 vault_id: { type: string }
3314 scope:
3315 type: string
3316 enum: [personal, project, org]
3317 flow_id: { type: string }
3318 flow_version: { type: string }
3319 allowed_tools:
3320 type: array
3321 items: { type: string }
3322 allowed_harnesses:
3323 type: array
3324 items: { type: string }
3325 expires_at: { type: string, format: date-time }
3326 issued_at: { type: string, format: date-time }
3327 revoked_at: { type: string, format: date-time, nullable: true }
3328 actor_hash: { type: string }
3329 max_invocations: { type: integer }
3330 invocation_count: { type: integer }
3331
3332 FlowExternalGrantMintResponse:
3333 type: object
3334 required: [schema, grant, bearer, expires_at]
3335 properties:
3336 schema:
3337 type: string
3338 enum: [knowtation.flow_external_grant_mint/v0]
3339 grant: { $ref: '#/components/schemas/FlowExternalGrant' }
3340 bearer: { type: string }
3341 expires_at: { type: string, format: date-time }
3342
3343 FlowExternalGrantListResponse:
3344 type: object
3345 required: [schema, vault_id, grants]
3346 properties:
3347 schema:
3348 type: string
3349 enum: [knowtation.flow_external_grant_list/v0]
3350 vault_id: { type: string }
3351 grants:
3352 type: array
3353 items: { $ref: '#/components/schemas/FlowExternalGrant' }
3354
3355 AgentIdentityRegisterRequest:
3356 type: object
3357 required: [kind]
3358 properties:
3359 kind:
3360 type: string
3361 enum: [user_owned, org_owned, delegate]
3362 agent_id: { type: string }
3363 label: { type: string }
3364 scope_ceiling:
3365 type: string
3366 enum: [personal, project, org]
3367
3368 DelegationProposalResponse:
3369 type: object
3370 required: [schema, proposal_id, intent]
3371 properties:
3372 schema:
3373 type: string
3374 enum: [knowtation.delegation_proposal/v0]
3375 proposal_id: { type: string }
3376 intent: { type: string }
3377 agent_id: { type: string }
3378 consent_id: { type: string }
3379
3380 AgentIdentity:
3381 type: object
3382 required:
3383 - schema
3384 - agent_id
3385 - kind
3386 - owner_ref
3387 - vault_id
3388 - scope_ceiling
3389 - status
3390 - created
3391 - updated
3392 properties:
3393 schema:
3394 type: string
3395 enum: [knowtation.agent_identity/v0]
3396 agent_id: { type: string }
3397 kind:
3398 type: string
3399 enum: [user_owned, org_owned, delegate]
3400 owner_ref: { type: string }
3401 vault_id: { type: string }
3402 scope_ceiling:
3403 type: string
3404 enum: [personal, project, org]
3405 label: { type: string }
3406 status:
3407 type: string
3408 enum: [active, suspended, revoked]
3409 created: { type: string, format: date-time }
3410 updated: { type: string, format: date-time }
3411
3412 AgentIdentityListResponse:
3413 type: object
3414 required: [schema, vault_id, identities]
3415 properties:
3416 schema:
3417 type: string
3418 enum: [knowtation.agent_identity_list/v0]
3419 vault_id: { type: string }
3420 identities:
3421 type: array
3422 items: { $ref: '#/components/schemas/AgentIdentity' }
3423
3424 DelegationConsentProposeRequest:
3425 type: object
3426 required: [delegate_agent_id, scope]
3427 properties:
3428 delegate_agent_id: { type: string }
3429 scope:
3430 type: string
3431 enum: [personal, project, org]
3432 workspace_id: { type: string }
3433 allowed_flow_ids:
3434 type: array
3435 items: { type: string }
3436 allowed_task_kinds:
3437 type: array
3438 items: { type: string }
3439 allowed_task_ids:
3440 type: array
3441 items: { type: string }
3442 expires_at: { type: string, format: date-time }
3443
3444 DelegationConsentProposeResponse:
3445 type: object
3446 required: [schema, proposal_id, intent, consent_id]
3447 properties:
3448 schema:
3449 type: string
3450 enum: [knowtation.delegation_proposal/v0]
3451 proposal_id: { type: string }
3452 intent: { type: string }
3453 consent_id: { type: string }
3454 consent_preview: { $ref: '#/components/schemas/DelegationConsent' }
3455
3456 DelegationConsent:
3457 type: object
3458 required:
3459 - schema
3460 - consent_id
3461 - principal_ref
3462 - delegate_agent_id
3463 - scope
3464 - revoked_at
3465 - evidence_ref
3466 - created
3467 properties:
3468 schema:
3469 type: string
3470 enum: [knowtation.delegation_consent/v0]
3471 consent_id: { type: string }
3472 principal_ref: { type: string }
3473 delegate_agent_id: { type: string }
3474 scope:
3475 type: string
3476 enum: [personal, project, org]
3477 workspace_id: { type: string }
3478 allowed_flow_ids:
3479 type: array
3480 items: { type: string }
3481 allowed_task_kinds:
3482 type: array
3483 items: { type: string }
3484 allowed_task_ids:
3485 type: array
3486 items: { type: string }
3487 expires_at: { type: string, format: date-time }
3488 revoked_at: { type: string, format: date-time, nullable: true }
3489 evidence_ref: { type: string }
3490 created: { type: string, format: date-time }
3491
3492 DelegationGrantMintRequest:
3493 type: object
3494 required: [consent_id, actor_agent_id]
3495 properties:
3496 consent_id: { type: string }
3497 actor_agent_id: { type: string }
3498 task_ref: { type: string }
3499 run_ref: { type: string }
3500 flow_id: { type: string }
3501 flow_version: { type: string }
3502 ttl_seconds: { type: integer, minimum: 1 }
3503
3504 DelegationGrant:
3505 type: object
3506 required:
3507 - schema
3508 - grant_id
3509 - consent_id
3510 - actor_agent_id
3511 - principal_ref
3512 - scope
3513 - expires_at
3514 - revoked_at
3515 - action_count
3516 - issued_at
3517 properties:
3518 schema:
3519 type: string
3520 enum: [knowtation.delegation_grant/v0]
3521 grant_id: { type: string }
3522 consent_id: { type: string }
3523 actor_agent_id: { type: string }
3524 principal_ref: { type: string }
3525 scope:
3526 type: string
3527 enum: [personal, project, org]
3528 workspace_id: { type: string }
3529 task_ref: { type: string }
3530 run_ref: { type: string }
3531 flow_id: { type: string }
3532 flow_version: { type: string }
3533 expires_at: { type: string, format: date-time }
3534 revoked_at: { type: string, format: date-time, nullable: true }
3535 max_actions: { type: integer }
3536 action_count: { type: integer }
3537 issued_at: { type: string, format: date-time }
3538
3539 DelegationGrantMintResponse:
3540 type: object
3541 required: [schema, grant, bearer, expires_at]
3542 properties:
3543 schema:
3544 type: string
3545 enum: [knowtation.delegation_grant_mint/v0]
3546 grant: { $ref: '#/components/schemas/DelegationGrant' }
3547 bearer: { type: string }
3548 expires_at: { type: string, format: date-time }
3549
3550 DelegationGrantListResponse:
3551 type: object
3552 required: [schema, vault_id, grants]
3553 properties:
3554 schema:
3555 type: string
3556 enum: [knowtation.delegation_grant_list/v0]
3557 vault_id: { type: string }
3558 grants:
3559 type: array
3560 items: { $ref: '#/components/schemas/DelegationGrant' }
3561
3562 DelegationAuditAppendRequest:
3563 type: object
3564 required: [grant_id, actor_agent_id, action, evidence_refs]
3565 properties:
3566 grant_id: { type: string }
3567 actor_agent_id: { type: string }
3568 principal_ref: { type: string }
3569 action:
3570 type: string
3571 enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]
3572 evidence_refs:
3573 type: array
3574 minItems: 1
3575 items: { type: string }
3576 task_ref: { type: string }
3577 run_ref: { type: string }
3578 flow_id: { type: string }
3579 flow_version: { type: string }
3580 step_id: { type: string }
3581 execution_location:
3582 type: string
3583 enum: [local, hosted, hybrid]
3584
3585 DelegationAudit:
3586 type: object
3587 required:
3588 - schema
3589 - audit_id
3590 - grant_id
3591 - actor_agent_id
3592 - principal_ref
3593 - action
3594 - evidence_refs
3595 - occurred_at
3596 properties:
3597 schema:
3598 type: string
3599 enum: [knowtation.delegation_audit/v0]
3600 audit_id: { type: string }
3601 grant_id: { type: string }
3602 actor_agent_id: { type: string }
3603 principal_ref: { type: string }
3604 task_ref: { type: string }
3605 run_ref: { type: string }
3606 flow_id: { type: string }
3607 flow_version: { type: string }
3608 step_id: { type: string }
3609 action:
3610 type: string
3611 enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]
3612 evidence_refs:
3613 type: array
3614 items: { type: string }
3615 occurred_at: { type: string, format: date-time }
3616 execution_location:
3617 type: string
3618 enum: [local, hosted, hybrid]
3619
3620 FlowProjectResponse:
3621 type: object
3622 required: [schema, vault_id, projection, staleness, generator]
3623 properties:
3624 schema:
3625 type: string
3626 enum: [knowtation.flow_project/v0]
3627 vault_id: { type: string }
3628 projection: { $ref: '#/components/schemas/FlowProjection' }
3629 staleness: { $ref: '#/components/schemas/FlowProjectionStaleness' }
3630 generator: { $ref: '#/components/schemas/FlowProjectionGenerator' }
3631
3632 FlowProjection:
3633 type: object
3634 required: [schema, flow_id, flow_version, harness, rendered, generated_from_canonical, editable]
3635 properties:
3636 schema:
3637 type: string
3638 enum: [knowtation.flow_projection/v0]
3639 flow_id: { type: string }
3640 flow_version: { type: string }
3641 harness:
3642 type: string
3643 enum: [cursor_rule, cursor_skill, mcp_prompt, cli_runbook, agent_bundle]
3644 rendered:
3645 type: string
3646 maxLength: 65536
3647 generated_from_canonical:
3648 type: boolean
3649 enum: [true]
3650 editable:
3651 type: boolean
3652 enum: [false]
3653 fidelity:
3654 type: object
3655 required: [dropped_fields]
3656 properties:
3657 dropped_fields:
3658 type: array
3659 items: { type: string }
3660 notes: { type: string }
3661
3662 FlowProjectionStaleness:
3663 type: object
3664 required: [stale, projection_version, latest_version]
3665 properties:
3666 stale: { type: boolean }
3667 projection_version: { type: string }
3668 latest_version: { type: string }
3669
3670 FlowProjectionGenerator:
3671 type: object
3672 required: [generator_version, content_hash, generated_at]
3673 properties:
3674 generator_version: { type: string }
3675 content_hash: { type: string }
3676 generated_at: { type: string }
3677
3678 Flow:
3679 type: object
3680 required: [schema, flow_id, title, version, scope, summary, steps, updated, truncated]
3681 properties:
3682 schema:
3683 type: string
3684 enum: [knowtation.flow/v0]
3685 flow_id: { type: string }
3686 title: { type: string }
3687 version: { type: string }
3688 scope:
3689 type: string
3690 enum: [personal, project, org]
3691 summary: { type: string }
3692 tags:
3693 type: array
3694 maxItems: 32
3695 items: { type: string }
3696 steps:
3697 type: array
3698 maxItems: 100
3699 items: { type: string }
3700 inputs:
3701 type: array
3702 items:
3703 type: object
3704 required: [name, type, required]
3705 properties:
3706 name: { type: string }
3707 type: { type: string }
3708 required: { type: boolean }
3709 vault_mirror_path: { type: string, nullable: true }
3710 updated: { type: string }
3711 truncated: { type: boolean }
3712
3713 FlowStep:
3714 type: object
3715 required: [schema, step_id, flow_id, ordinal, owned_job, instruction, trigger, when_not_to_run, boundaries, output_shape, verification, automatable]
3716 properties:
3717 schema:
3718 type: string
3719 enum: [knowtation.flow_step/v0]
3720 step_id: { type: string }
3721 flow_id: { type: string }
3722 ordinal: { type: integer, minimum: 1 }
3723 owned_job: { type: string }
3724 instruction: { type: string }
3725 trigger: { type: string }
3726 when_not_to_run: { type: string }
3727 requires:
3728 type: array
3729 items:
3730 type: object
3731 required: [kind, id]
3732 properties:
3733 kind:
3734 type: string
3735 enum: [vault_scope, tool, file, artifact]
3736 id: { type: string }
3737 boundaries:
3738 type: array
3739 items: { type: string }
3740 skill_refs:
3741 type: array
3742 items:
3743 type: object
3744 required: [kind, id]
3745 properties:
3746 kind:
3747 type: string
3748 enum: [mcp_prompt, skill_pack, cli, external_tool]
3749 id: { type: string }
3750 inputs:
3751 type: array
3752 items:
3753 type: object
3754 required: [name, from]
3755 properties:
3756 name: { type: string }
3757 from: { type: string }
3758 outputs:
3759 type: array
3760 items:
3761 type: object
3762 required: [name, type]
3763 properties:
3764 name: { type: string }
3765 type: { type: string }
3766 output_shape: { type: string }
3767 verification:
3768 type: object
3769 required: [kind, evidence_required, description]
3770 properties:
3771 kind:
3772 type: string
3773 enum: [human_review, artifact_exists, value_match, test_pass, agent_check]
3774 evidence_required: { type: boolean }
3775 description: { type: string }
3776 automatable:
3777 type: string
3778 enum: [manual, agent_assisted, automatable]
File History 1 commit
sha256:c2dbf04d56308f3bbf2d06e6d2eb022b8948b1e827195fe525a44e5e18d5f9c0 feat(auth): Phase B Connect cloud agent (RFC 8628) + Hermes… Human minor ⚠ 10 days ago