aaronrene / knowtation public
openapi.yaml yaml
2,950 lines 92.0 KB
Raw
sha256:0279cd72f3b5db53d740fb647a4b0bf68d2c327a0d05cbcb6234c2b128d57c11 feat(delegation): implement 7C-6 agent identity/delegation … Human minor ⚠ breaking 33 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
23 security:
24 - BearerAuth: []
25
26 paths:
27 /health:
28 get:
29 tags: [Health]
30 summary: Health check
31 security: []
32 responses:
33 '200':
34 description: Hub is up
35 content:
36 application/json:
37 schema: { type: object, properties: { ok: { type: boolean } }, required: [ok] }
38
39 /api/v1/auth/session:
40 get:
41 tags: [Auth]
42 summary: C7 Session introspection — current identity and scopes
43 description: |
44 Returns the verified identity and derived API scopes for the caller. Accepts only a
45 `Bearer` JWT in the `Authorization` header — no cookie required, making it safe to call
46 cross-origin from Scooling or any other consumer.
47
48 The response is derived entirely from the signed token — no database call is made.
49 Scopes are role-derived today (C4 will replace this with per-user explicit grants without
50 changing the response shape).
51 security:
52 - bearerAuth: []
53 responses:
54 '200':
55 description: Verified session
56 content:
57 application/json:
58 schema:
59 type: object
60 required: [sub, provider, id, name, role, iat, exp, scopes]
61 properties:
62 sub:
63 type: string
64 description: Canonical user ID (`provider:id`)
65 example: google:104164334692309763642
66 provider:
67 type: string
68 enum: [google, github]
69 id:
70 type: string
71 description: Provider-specific user ID
72 name:
73 type: string
74 description: Display name (empty for refresh-path tokens)
75 role:
76 type: string
77 enum: [admin, member]
78 iat:
79 type: integer
80 description: Token issued-at (Unix seconds)
81 exp:
82 type: integer
83 description: Token expires-at (Unix seconds)
84 scopes:
85 type: array
86 items: { type: string }
87 description: Derived API scopes. `admin` role → `[vault:read, vault:write, admin]`; `member` → `[vault:read, vault:write]`
88 example: [vault:read, vault:write]
89 '401':
90 description: Missing, expired, or tampered token
91 content:
92 application/json:
93 schema:
94 type: object
95 properties:
96 error: { type: string }
97 code: { type: string, enum: [UNAUTHORIZED] }
98
99 /auth/providers:
100 get:
101 tags: [Auth]
102 summary: OAuth providers configured
103 security: []
104 responses:
105 '200':
106 content:
107 application/json:
108 schema:
109 type: object
110 properties:
111 google: { type: boolean }
112 github: { type: boolean }
113
114 /notes/facets:
115 get:
116 tags: [Notes]
117 summary: Projects, tags, folders for filter dropdowns
118 responses:
119 '200':
120 content:
121 application/json:
122 schema:
123 type: object
124 properties:
125 projects: { type: array, items: { type: string } }
126 tags: { type: array, items: { type: string } }
127 folders: { type: array, items: { type: string } }
128
129 /notes:
130 get:
131 tags: [Notes]
132 summary: List notes
133 parameters:
134 - name: folder
135 in: query
136 schema: { type: string }
137 - name: project
138 in: query
139 schema: { type: string }
140 - name: tag
141 in: query
142 schema: { type: string }
143 - name: since
144 in: query
145 schema: { type: string }
146 - name: until
147 in: query
148 schema: { type: string }
149 - name: limit
150 in: query
151 schema: { type: integer, minimum: 0, maximum: 100 }
152 - name: offset
153 in: query
154 schema: { type: integer, minimum: 0 }
155 - name: order
156 in: query
157 schema: { type: string, enum: [date, date-asc] }
158 - name: fields
159 in: query
160 schema: { type: string, enum: [path, path+metadata, full] }
161 - name: count_only
162 in: query
163 schema: { type: boolean }
164 responses:
165 '200':
166 content:
167 application/json:
168 schema:
169 oneOf:
170 - type: object
171 properties:
172 notes: { type: array, items: { $ref: '#/components/schemas/NoteListItem' } }
173 total: { type: integer }
174 - type: object
175 properties:
176 total: { type: integer }
177 post:
178 tags: [Notes]
179 summary: Write or update a note
180 requestBody:
181 required: true
182 content:
183 application/json:
184 schema:
185 type: object
186 required: [path]
187 properties:
188 path: { type: string }
189 body: { type: string }
190 frontmatter: { type: object }
191 append: { type: boolean }
192 responses:
193 '200':
194 content:
195 application/json:
196 schema: { type: object, properties: { path: { type: string }, written: { type: boolean } } }
197 '400':
198 '500':
199 content:
200 application/json:
201 schema: { $ref: '#/components/schemas/Error' }
202
203 /notes/{path}:
204 get:
205 tags: [Notes]
206 summary: Get one note by path
207 parameters:
208 - name: path
209 in: path
210 required: true
211 schema: { type: string }
212 responses:
213 '200':
214 content:
215 application/json:
216 schema: { $ref: '#/components/schemas/NoteFull' }
217 '404':
218 content:
219 application/json:
220 schema: { $ref: '#/components/schemas/Error' }
221
222 /note-outline:
223 get:
224 tags: [Notes]
225 summary: Body-free NoteOutline headings for one note
226 description: >
227 Returns knowtation.note_outline/v1 metadata for one authorized vault-relative note.
228 The response excludes note body text, snippets, full frontmatter, absolute paths,
229 provider payloads, MCP resource URIs, summaries, vectors, OCR, PageIndex output,
230 persistence records, and write-back state.
231 parameters:
232 - name: path
233 in: query
234 required: true
235 schema: { type: string }
236 description: Vault-relative Markdown note path.
237 responses:
238 '200':
239 content:
240 application/json:
241 schema: { $ref: '#/components/schemas/NoteOutline' }
242 '400':
243 content:
244 application/json:
245 schema: { $ref: '#/components/schemas/Error' }
246 '401':
247 content:
248 application/json:
249 schema: { $ref: '#/components/schemas/Error' }
250 '403':
251 content:
252 application/json:
253 schema: { $ref: '#/components/schemas/Error' }
254 '404':
255 content:
256 application/json:
257 schema: { $ref: '#/components/schemas/Error' }
258 '502':
259 content:
260 application/json:
261 schema: { $ref: '#/components/schemas/Error' }
262
263 /document-tree:
264 get:
265 tags: [Notes]
266 summary: Body-free DocumentTree heading hierarchy for one note
267 description: >
268 Returns knowtation.document_tree/v0 metadata for one authorized vault-relative note.
269 The response excludes note body text, snippets, full frontmatter, absolute paths,
270 provider payloads, MCP resource URIs, summaries, vectors, OCR, PageIndex output,
271 persistence records, sidecars, LLM calls, and write-back state.
272 parameters:
273 - name: path
274 in: query
275 required: true
276 schema: { type: string }
277 description: Vault-relative Markdown note path.
278 responses:
279 '200':
280 content:
281 application/json:
282 schema: { $ref: '#/components/schemas/DocumentTree' }
283 '400':
284 content:
285 application/json:
286 schema: { $ref: '#/components/schemas/Error' }
287 '401':
288 content:
289 application/json:
290 schema: { $ref: '#/components/schemas/Error' }
291 '403':
292 content:
293 application/json:
294 schema: { $ref: '#/components/schemas/Error' }
295 '404':
296 content:
297 application/json:
298 schema: { $ref: '#/components/schemas/Error' }
299 '502':
300 content:
301 application/json:
302 schema: { $ref: '#/components/schemas/Error' }
303
304 /calendar/timeline:
305 get:
306 tags: [Calendar]
307 summary: Merged note-date and external-event timeline (self-hosted)
308 description: >
309 Returns knowtation.calendar_timeline/v0 items for an authorized vault.
310 Merges note-date buckets and stored calendar events. No OAuth tokens or connector secrets.
311 parameters:
312 - name: from
313 in: query
314 required: true
315 schema: { type: string }
316 description: Range start (YYYY-MM-DD or ISO8601).
317 - name: to
318 in: query
319 required: true
320 schema: { type: string }
321 description: Range end (YYYY-MM-DD or ISO8601).
322 - name: layers
323 in: query
324 required: false
325 schema: { type: string }
326 description: Comma-separated layers (`notes`, `events`). Default both.
327 - name: source_calendar_ids
328 in: query
329 required: false
330 schema: { type: string }
331 description: Comma-separated source calendar ids to include for the events layer.
332 responses:
333 '200':
334 content:
335 application/json:
336 schema: { $ref: '#/components/schemas/CalendarTimeline' }
337 '400':
338 content:
339 application/json:
340 schema: { $ref: '#/components/schemas/Error' }
341 '401':
342 content:
343 application/json:
344 schema: { $ref: '#/components/schemas/Error' }
345 '403':
346 content:
347 application/json:
348 schema: { $ref: '#/components/schemas/Error' }
349
350 /calendar/agent-context:
351 get:
352 tags: [Calendar]
353 summary: Tier-enforced calendar context for agents (self-hosted)
354 description: >
355 Returns knowtation.calendar_agent_context/v0 — redacted calendar events an agent
356 may see. Enforced server-side: calendars with enabled_for_agents=false contribute
357 nothing; per-calendar agent_context_tier_max and the org policy cap clamp the tier;
358 the v0 retrieval ceiling is tier 2. Agent visibility is independent of
359 enabled_for_display. Tier 1 omits the event summary; tier 0 returns no events.
360 Calendar text is untrusted prompt content.
361 parameters:
362 - name: from
363 in: query
364 required: true
365 schema: { type: string }
366 description: Range start (YYYY-MM-DD or ISO8601).
367 - name: to
368 in: query
369 required: true
370 schema: { type: string }
371 description: Range end (YYYY-MM-DD or ISO8601).
372 - name: agent_context_tier
373 in: query
374 required: true
375 schema: { type: integer, minimum: 0, maximum: 2 }
376 description: Requested agent tier (0 none, 1 busy blocks, 2 titles + label). Clamped by caps.
377 - name: source_calendar_ids
378 in: query
379 required: false
380 schema: { type: string }
381 description: Comma-separated source calendar ids to restrict the agent scope.
382 responses:
383 '200':
384 content:
385 application/json:
386 schema: { $ref: '#/components/schemas/CalendarAgentContext' }
387 '400':
388 content:
389 application/json:
390 schema: { $ref: '#/components/schemas/Error' }
391 '401':
392 content:
393 application/json:
394 schema: { $ref: '#/components/schemas/Error' }
395 '403':
396 content:
397 application/json:
398 schema: { $ref: '#/components/schemas/Error' }
399
400 /calendar/source-calendars:
401 get:
402 tags: [Calendar]
403 summary: List source calendars and display/agent toggles (self-hosted)
404 responses:
405 '200':
406 content:
407 application/json:
408 schema: { $ref: '#/components/schemas/SourceCalendarList' }
409 '401':
410 content:
411 application/json:
412 schema: { $ref: '#/components/schemas/Error' }
413 '403':
414 content:
415 application/json:
416 schema: { $ref: '#/components/schemas/Error' }
417
418 /calendar/source-calendars/{id}:
419 patch:
420 tags: [Calendar]
421 summary: Update source calendar display/agent toggles (self-hosted)
422 description: >
423 Partial update for enabled_for_display, enabled_for_agents, agent_context_tier_max (0–4),
424 and optional user_group. Org policy may cap agent_context_tier_max via
425 KNOWTATION_CALENDAR_AGENT_TIER_MAX_CAP or data/hub_calendar_policy.json.
426 parameters:
427 - name: id
428 in: path
429 required: true
430 schema: { type: string }
431 description: Source calendar id.
432 requestBody:
433 required: true
434 content:
435 application/json:
436 schema: { $ref: '#/components/schemas/SourceCalendarPatchRequest' }
437 responses:
438 '200':
439 content:
440 application/json:
441 schema: { $ref: '#/components/schemas/SourceCalendarPatchResult' }
442 '400':
443 content:
444 application/json:
445 schema: { $ref: '#/components/schemas/Error' }
446 '401':
447 content:
448 application/json:
449 schema: { $ref: '#/components/schemas/Error' }
450 '403':
451 content:
452 application/json:
453 schema: { $ref: '#/components/schemas/Error' }
454 '404':
455 content:
456 application/json:
457 schema: { $ref: '#/components/schemas/Error' }
458
459 /calendar/events/import:
460 post:
461 tags: [Calendar]
462 summary: Import ICS text into the local event store (read-only, self-hosted)
463 requestBody:
464 required: true
465 content:
466 application/json:
467 schema: { $ref: '#/components/schemas/CalendarIcsImportRequest' }
468 responses:
469 '200':
470 content:
471 application/json:
472 schema: { $ref: '#/components/schemas/CalendarIcsImportResult' }
473 '400':
474 content:
475 application/json:
476 schema: { $ref: '#/components/schemas/Error' }
477 '401':
478 content:
479 application/json:
480 schema: { $ref: '#/components/schemas/Error' }
481 '403':
482 content:
483 application/json:
484 schema: { $ref: '#/components/schemas/Error' }
485
486 /flows:
487 get:
488 tags: [Flows]
489 summary: List scope-visible flows (content-minimized)
490 description: >
491 Returns knowtation.flow_list/v0 summaries for flows visible in the caller's
492 authorized workspace scope. Scope query param narrows only — never widens.
493 Step bodies are never included in list responses.
494 parameters:
495 - name: scope
496 in: query
497 schema: { type: string, enum: [personal, project, org] }
498 description: Narrow within authorized scopes only.
499 - name: tag
500 in: query
501 schema: { type: string }
502 description: Filter by single tag membership.
503 - name: limit
504 in: query
505 schema: { type: integer, minimum: 1, maximum: 200 }
506 description: Max summaries (default 200).
507 responses:
508 '200':
509 content:
510 application/json:
511 schema: { $ref: '#/components/schemas/FlowListResponse' }
512 '400':
513 content:
514 application/json:
515 schema: { $ref: '#/components/schemas/Error' }
516 '401':
517 content:
518 application/json:
519 schema: { $ref: '#/components/schemas/Error' }
520 '403':
521 content:
522 application/json:
523 schema: { $ref: '#/components/schemas/Error' }
524 post:
525 tags: [Flows]
526 summary: Propose a new Flow (review-before-write)
527 description: >
528 Validates a knowtation.flow/v0 + flow_step/v0 bundle, resolves write
529 authority server-side (scope × role, deny-by-default), and creates a
530 standard proposal targeting the Flow's mirror note (SD-4). Returns a
531 knowtation.flow_proposal/v0 envelope (pointers/labels only). Gated by
532 FLOW_AUTHORING_WRITES — when off returns 403 FLOW_AUTHORING_DISABLED.
533 No Flow index write happens here; the index changes only at approve→apply.
534 requestBody:
535 required: true
536 content:
537 application/json:
538 schema: { $ref: '#/components/schemas/FlowProposeRequest' }
539 responses:
540 '201':
541 content:
542 application/json:
543 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
544 '400':
545 content:
546 application/json:
547 schema: { $ref: '#/components/schemas/Error' }
548 '401':
549 content:
550 application/json:
551 schema: { $ref: '#/components/schemas/Error' }
552 '403':
553 content:
554 application/json:
555 schema: { $ref: '#/components/schemas/Error' }
556 '409':
557 content:
558 application/json:
559 schema: { $ref: '#/components/schemas/Error' }
560
561 /flows/import:
562 post:
563 tags: [Flows]
564 summary: Import a portable Flow bundle as a scope-checked proposal
565 description: >
566 Routes a portable { flow, steps } bundle through the same propose path.
567 The bundle scope is validated against the actor's write tier; unwritable
568 ⇒ 403 FLOW_IMPORT_SCOPE_DENIED, malformed ⇒ 400 FLOW_IMPORT_BUNDLE_MALFORMED.
569 Lineage pointers (external_ref / source_vault_hint) are preserved. Never
570 auto-applied — creates a proposed proposal. Gated by FLOW_AUTHORING_WRITES.
571 requestBody:
572 required: true
573 content:
574 application/json:
575 schema: { $ref: '#/components/schemas/FlowImportRequest' }
576 responses:
577 '201':
578 content:
579 application/json:
580 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
581 '400':
582 content:
583 application/json:
584 schema: { $ref: '#/components/schemas/Error' }
585 '401':
586 content:
587 application/json:
588 schema: { $ref: '#/components/schemas/Error' }
589 '403':
590 content:
591 application/json:
592 schema: { $ref: '#/components/schemas/Error' }
593 '409':
594 content:
595 application/json:
596 schema: { $ref: '#/components/schemas/Error' }
597
598 /flows/capture/observe:
599 post:
600 tags: [Flows]
601 summary: Observe content-minimized session signals (capture detection)
602 description: >
603 Runs bounded structural detectors when FLOW_CAPTURE_DETECTION_ENABLED is on.
604 Creates/updates flow_candidate/v0 records; returns content-minimized summaries.
605 When detection is off, returns detection_authorized=false with no store mutation.
606 requestBody:
607 required: true
608 content:
609 application/json:
610 schema:
611 type: object
612 required: [session_id, step_sequence_refs, observed_counts]
613 responses:
614 '200':
615 description: Observe envelope
616 '400':
617 content:
618 application/json:
619 schema: { $ref: '#/components/schemas/Error' }
620 '403':
621 content:
622 application/json:
623 schema: { $ref: '#/components/schemas/Error' }
624
625 /flows/candidates:
626 get:
627 tags: [Flows]
628 summary: List flow capture candidates (read store)
629 description: Returns pending_review candidate summaries; read path does not require detection sub-gate.
630 parameters:
631 - name: scope
632 in: query
633 schema: { type: string, enum: [personal, project, org] }
634 - name: include_low_confidence
635 in: query
636 schema: { type: boolean }
637 - name: limit
638 in: query
639 schema: { type: integer, minimum: 1, maximum: 50 }
640 responses:
641 '200':
642 description: Candidate list envelope
643 '400':
644 content:
645 application/json:
646 schema: { $ref: '#/components/schemas/Error' }
647
648 /flows/candidates/{candidate_id}/propose:
649 post:
650 tags: [Flows]
651 summary: Propose candidate promotion (review-before-write)
652 description: >
653 Creates a flow_candidate_promote or flow_candidate_merge proposal.
654 Gated by FLOW_CAPTURE_WRITES_ENABLED (default off).
655 parameters:
656 - name: candidate_id
657 in: path
658 required: true
659 schema: { type: string }
660 requestBody:
661 required: true
662 content:
663 application/json:
664 schema:
665 type: object
666 required: [confirmed_scope, intent]
667 responses:
668 '201':
669 description: Capture proposal envelope
670 '403':
671 content:
672 application/json:
673 schema: { $ref: '#/components/schemas/Error' }
674 '404':
675 content:
676 application/json:
677 schema: { $ref: '#/components/schemas/Error' }
678 '409':
679 content:
680 application/json:
681 schema: { $ref: '#/components/schemas/Error' }
682
683 /flows/candidates/{candidate_id}/dismiss:
684 post:
685 tags: [Flows]
686 summary: Propose candidate dismissal
687 description: >
688 Creates a flow_candidate_dismiss proposal; on approve candidate status becomes rejected.
689 Gated by FLOW_CAPTURE_WRITES_ENABLED (default off).
690 parameters:
691 - name: candidate_id
692 in: path
693 required: true
694 schema: { type: string }
695 requestBody:
696 required: true
697 content:
698 application/json:
699 schema:
700 type: object
701 required: [intent]
702 responses:
703 '201':
704 description: Capture proposal envelope
705 '403':
706 content:
707 application/json:
708 schema: { $ref: '#/components/schemas/Error' }
709 '404':
710 content:
711 application/json:
712 schema: { $ref: '#/components/schemas/Error' }
713
714 /flows/{id}/proposals:
715 post:
716 tags: [Flows]
717 summary: Propose an edit to an existing Flow (review-before-write)
718 description: >
719 Like POST /flows but for an edit. Requires base_version + base_state_id
720 (the flowst1_ optimistic-concurrency token); a mismatch at propose or
721 approve time ⇒ 409 FLOW_LINEAGE_CONFLICT. flow.version must be strictly
722 greater than base_version. Editing a flow the actor cannot read ⇒ 404
723 unknown_flow (no existence leak). Gated by FLOW_AUTHORING_WRITES.
724 parameters:
725 - name: id
726 in: path
727 required: true
728 schema: { type: string }
729 description: Flow id (flow_<slug>); must match the bundle's flow_id.
730 requestBody:
731 required: true
732 content:
733 application/json:
734 schema: { $ref: '#/components/schemas/FlowProposeEditRequest' }
735 responses:
736 '201':
737 content:
738 application/json:
739 schema: { $ref: '#/components/schemas/FlowProposalResponse' }
740 '400':
741 content:
742 application/json:
743 schema: { $ref: '#/components/schemas/Error' }
744 '401':
745 content:
746 application/json:
747 schema: { $ref: '#/components/schemas/Error' }
748 '403':
749 content:
750 application/json:
751 schema: { $ref: '#/components/schemas/Error' }
752 '404':
753 content:
754 application/json:
755 schema: { $ref: '#/components/schemas/Error' }
756 '409':
757 content:
758 application/json:
759 schema: { $ref: '#/components/schemas/Error' }
760
761 /flows/{id}/projection:
762 get:
763 tags: [Flows]
764 summary: Derive a read-only harness projection of a canonical flow
765 description: >
766 Renders the canonical flow (latest visible, or pinned ?version) into the requested
767 harness as knowtation.flow_project/v0. Derived and read-only — generated_from_canonical
768 is always true and editable is always false. No secrets appear in rendered text.
769 parameters:
770 - name: id
771 in: path
772 required: true
773 schema: { type: string }
774 - name: harness
775 in: query
776 required: true
777 schema:
778 type: string
779 enum: [cursor_rule, cursor_skill, mcp_prompt, cli_runbook, agent_bundle]
780 - name: version
781 in: query
782 schema: { type: string }
783 responses:
784 '200':
785 content:
786 application/json:
787 schema: { $ref: '#/components/schemas/FlowProjectResponse' }
788 '400':
789 content:
790 application/json:
791 schema: { $ref: '#/components/schemas/Error' }
792 '401':
793 content:
794 application/json:
795 schema: { $ref: '#/components/schemas/Error' }
796 '403':
797 content:
798 application/json:
799 schema: { $ref: '#/components/schemas/Error' }
800 '404':
801 content:
802 application/json:
803 schema: { $ref: '#/components/schemas/Error' }
804
805 /flows/{id}/external-grants:
806 post:
807 tags: [Flows]
808 summary: Mint a short-lived external-agent grant (gated; default off)
809 description: >
810 Mints knowtation.flow_external_grant/v0 for a pinned flow version and requested tools.
811 Returns a one-time bearer at mint only. Requires FLOW_EXTERNAL_AGENT_ENABLED.
812 parameters:
813 - name: id
814 in: path
815 required: true
816 schema: { type: string }
817 requestBody:
818 required: true
819 content:
820 application/json:
821 schema: { $ref: '#/components/schemas/FlowExternalGrantMintRequest' }
822 responses:
823 '201':
824 content:
825 application/json:
826 schema: { $ref: '#/components/schemas/FlowExternalGrantMintResponse' }
827 '400':
828 content:
829 application/json:
830 schema: { $ref: '#/components/schemas/Error' }
831 '403':
832 content:
833 application/json:
834 schema: { $ref: '#/components/schemas/Error' }
835 '404':
836 content:
837 application/json:
838 schema: { $ref: '#/components/schemas/Error' }
839
840 /flows/external-grants:
841 get:
842 tags: [Flows]
843 summary: List external-agent grant metadata (no bearer)
844 parameters:
845 - name: flow_id
846 in: query
847 schema: { type: string }
848 responses:
849 '200':
850 content:
851 application/json:
852 schema: { $ref: '#/components/schemas/FlowExternalGrantListResponse' }
853 '403':
854 content:
855 application/json:
856 schema: { $ref: '#/components/schemas/Error' }
857
858 /flows/external-grants/{grant_id}:
859 delete:
860 tags: [Flows]
861 summary: Revoke an external-agent grant
862 parameters:
863 - name: grant_id
864 in: path
865 required: true
866 schema: { type: string }
867 responses:
868 '200':
869 content:
870 application/json:
871 schema: { $ref: '#/components/schemas/FlowExternalGrant' }
872 '403':
873 content:
874 application/json:
875 schema: { $ref: '#/components/schemas/Error' }
876 '404':
877 content:
878 application/json:
879 schema: { $ref: '#/components/schemas/Error' }
880
881 /agents/identities:
882 post:
883 tags: [Delegation]
884 summary: Propose agent identity registration (SD-4; gated; default off)
885 description: >
886 Creates an SD-4 proposal with intent agent_identity_register. Requires DELEGATION_ENABLED.
887 requestBody:
888 required: true
889 content:
890 application/json:
891 schema: { $ref: '#/components/schemas/AgentIdentityRegisterRequest' }
892 responses:
893 '201':
894 content:
895 application/json:
896 schema: { $ref: '#/components/schemas/DelegationProposalResponse' }
897 '403':
898 content:
899 application/json:
900 schema: { $ref: '#/components/schemas/Error' }
901 get:
902 tags: [Delegation]
903 summary: List agent identities (gated; default off)
904 parameters:
905 - name: kind
906 in: query
907 schema:
908 type: string
909 enum: [user_owned, org_owned, delegate]
910 - name: status
911 in: query
912 schema:
913 type: string
914 enum: [active, suspended, revoked]
915 responses:
916 '200':
917 content:
918 application/json:
919 schema: { $ref: '#/components/schemas/AgentIdentityListResponse' }
920 '403':
921 content:
922 application/json:
923 schema: { $ref: '#/components/schemas/Error' }
924
925 /delegation/consents:
926 post:
927 tags: [Delegation]
928 summary: Propose delegation consent (SD-4; gated; default off)
929 requestBody:
930 required: true
931 content:
932 application/json:
933 schema: { $ref: '#/components/schemas/DelegationConsentProposeRequest' }
934 responses:
935 '201':
936 content:
937 application/json:
938 schema: { $ref: '#/components/schemas/DelegationConsentProposeResponse' }
939 '403':
940 content:
941 application/json:
942 schema: { $ref: '#/components/schemas/Error' }
943
944 /delegation/consents/{consent_id}:
945 delete:
946 tags: [Delegation]
947 summary: Revoke delegation consent
948 parameters:
949 - name: consent_id
950 in: path
951 required: true
952 schema: { type: string }
953 responses:
954 '200':
955 content:
956 application/json:
957 schema: { $ref: '#/components/schemas/DelegationConsent' }
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 /delegation/grants:
968 post:
969 tags: [Delegation]
970 summary: Mint short-lived delegation grant (gated; default off)
971 requestBody:
972 required: true
973 content:
974 application/json:
975 schema: { $ref: '#/components/schemas/DelegationGrantMintRequest' }
976 responses:
977 '201':
978 content:
979 application/json:
980 schema: { $ref: '#/components/schemas/DelegationGrantMintResponse' }
981 '403':
982 content:
983 application/json:
984 schema: { $ref: '#/components/schemas/Error' }
985 '404':
986 content:
987 application/json:
988 schema: { $ref: '#/components/schemas/Error' }
989 get:
990 tags: [Delegation]
991 summary: List delegation grant metadata (no bearer)
992 parameters:
993 - name: actor_agent_id
994 in: query
995 schema: { type: string }
996 responses:
997 '200':
998 content:
999 application/json:
1000 schema: { $ref: '#/components/schemas/DelegationGrantListResponse' }
1001 '403':
1002 content:
1003 application/json:
1004 schema: { $ref: '#/components/schemas/Error' }
1005
1006 /delegation/grants/{grant_id}:
1007 delete:
1008 tags: [Delegation]
1009 summary: Revoke delegation grant
1010 parameters:
1011 - name: grant_id
1012 in: path
1013 required: true
1014 schema: { type: string }
1015 responses:
1016 '200':
1017 content:
1018 application/json:
1019 schema: { $ref: '#/components/schemas/DelegationGrant' }
1020 '403':
1021 content:
1022 application/json:
1023 schema: { $ref: '#/components/schemas/Error' }
1024 '404':
1025 content:
1026 application/json:
1027 schema: { $ref: '#/components/schemas/Error' }
1028
1029 /delegation/audit:
1030 post:
1031 tags: [Delegation]
1032 summary: Append delegation audit entry (pointer-safe)
1033 requestBody:
1034 required: true
1035 content:
1036 application/json:
1037 schema: { $ref: '#/components/schemas/DelegationAuditAppendRequest' }
1038 responses:
1039 '201':
1040 content:
1041 application/json:
1042 schema: { $ref: '#/components/schemas/DelegationAudit' }
1043 '403':
1044 content:
1045 application/json:
1046 schema: { $ref: '#/components/schemas/Error' }
1047
1048 /flows/{id}:
1049 get:
1050 tags: [Flows]
1051 summary: Get one flow definition + ordered steps
1052 description: >
1053 Returns knowtation.flow_get/v0 with full flow definition and steps in ascending
1054 ordinal order. Missing and scope-invisible flows both return 404 unknown_flow.
1055 Step text is untrusted input — returned verbatim as data.
1056 parameters:
1057 - name: id
1058 in: path
1059 required: true
1060 schema: { type: string }
1061 description: Flow id (flow_<slug>).
1062 - name: version
1063 in: query
1064 schema: { type: string }
1065 description: Pin semver version; default latest visible.
1066 responses:
1067 '200':
1068 content:
1069 application/json:
1070 schema: { $ref: '#/components/schemas/FlowGetResponse' }
1071 '400':
1072 content:
1073 application/json:
1074 schema: { $ref: '#/components/schemas/Error' }
1075 '401':
1076 content:
1077 application/json:
1078 schema: { $ref: '#/components/schemas/Error' }
1079 '403':
1080 content:
1081 application/json:
1082 schema: { $ref: '#/components/schemas/Error' }
1083 '404':
1084 content:
1085 application/json:
1086 schema: { $ref: '#/components/schemas/Error' }
1087
1088 /flow-runs/{run_id}:
1089 get:
1090 tags: [Flows]
1091 summary: Get one flow run by run id
1092 description: >
1093 Returns knowtation.flow_run/v0 for a scope-visible run. Missing and
1094 scope-invisible runs both return 404 unknown_run.
1095 parameters:
1096 - name: run_id
1097 in: path
1098 required: true
1099 schema: { type: string }
1100 responses:
1101 '200':
1102 content:
1103 application/json:
1104 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1105 '404':
1106 content:
1107 application/json:
1108 schema: { $ref: '#/components/schemas/Error' }
1109
1110 /flows/{id}/runs:
1111 get:
1112 tags: [Flows]
1113 summary: List runs for a flow
1114 parameters:
1115 - name: id
1116 in: path
1117 required: true
1118 schema: { type: string }
1119 responses:
1120 '200':
1121 content:
1122 application/json:
1123 schema: { $ref: '#/components/schemas/FlowRunListResponse' }
1124 post:
1125 tags: [Flows]
1126 summary: Start a flow run
1127 description: >
1128 Gated by FLOW_RUN_WRITES_ENABLED (default off). Pins flow_version for the run life.
1129 parameters:
1130 - name: id
1131 in: path
1132 required: true
1133 schema: { type: string }
1134 requestBody:
1135 required: true
1136 content:
1137 application/json:
1138 schema:
1139 type: object
1140 required: [flow_version]
1141 properties:
1142 flow_version: { type: string }
1143 task_ref: { type: string }
1144 external_ref: { type: string }
1145 responses:
1146 '201':
1147 content:
1148 application/json:
1149 schema: { $ref: '#/components/schemas/FlowRunStartResponse' }
1150 '403':
1151 content:
1152 application/json:
1153 schema: { $ref: '#/components/schemas/Error' }
1154
1155 /flows/{id}/runs/{run_id}:
1156 get:
1157 tags: [Flows]
1158 summary: Get one flow run
1159 parameters:
1160 - name: id
1161 in: path
1162 required: true
1163 schema: { type: string }
1164 - name: run_id
1165 in: path
1166 required: true
1167 schema: { type: string }
1168 responses:
1169 '200':
1170 content:
1171 application/json:
1172 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1173 post:
1174 tags: [Flows]
1175 summary: Advance, record evidence, execute automatable, or submit review
1176 description: >
1177 Use dedicated sub-paths (/advance, /evidence, /execute-automatable, /submit-review).
1178 Run writes gated by FLOW_RUN_WRITES_ENABLED; automatable by FLOW_AUTOMATABLE_EXECUTION_ENABLED.
1179
1180 /flows/{id}/runs/{run_id}/advance:
1181 post:
1182 tags: [Flows]
1183 summary: Advance a step manually
1184 parameters:
1185 - name: id
1186 in: path
1187 required: true
1188 schema: { type: string }
1189 - name: run_id
1190 in: path
1191 required: true
1192 schema: { type: string }
1193 requestBody:
1194 required: true
1195 content:
1196 application/json:
1197 schema:
1198 type: object
1199 required: [step_id, to_status]
1200 properties:
1201 step_id: { type: string }
1202 to_status: { type: string }
1203 skip_reason: { type: string }
1204 responses:
1205 '200':
1206 content:
1207 application/json:
1208 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1209
1210 /flows/{id}/runs/{run_id}/evidence:
1211 post:
1212 tags: [Flows]
1213 summary: Record evidence pointer on a step
1214 parameters:
1215 - name: id
1216 in: path
1217 required: true
1218 schema: { type: string }
1219 - name: run_id
1220 in: path
1221 required: true
1222 schema: { type: string }
1223 requestBody:
1224 required: true
1225 content:
1226 application/json:
1227 schema:
1228 type: object
1229 required: [step_id, evidence_ref, pointer_kind]
1230 properties:
1231 step_id: { type: string }
1232 evidence_ref: { type: string }
1233 pointer_kind: { type: string }
1234 responses:
1235 '200':
1236 content:
1237 application/json:
1238 schema: { $ref: '#/components/schemas/FlowRunResponse' }
1239
1240 /flows/{id}/runs/{run_id}/execute-automatable:
1241 post:
1242 tags: [Flows]
1243 summary: Execute an automatable step (server orchestration stub)
1244 description: Requires valid knowtation.flow_execution_consent/v0. Gated by FLOW_AUTOMATABLE_EXECUTION_ENABLED.
1245 parameters:
1246 - name: id
1247 in: path
1248 required: true
1249 schema: { type: string }
1250 - name: run_id
1251 in: path
1252 required: true
1253 schema: { type: string }
1254 requestBody:
1255 required: true
1256 content:
1257 application/json:
1258 schema:
1259 type: object
1260 required: [step_id, consent_id]
1261 properties:
1262 step_id: { type: string }
1263 consent_id: { type: string }
1264 model_lane: { type: string }
1265 dry_run: { type: boolean }
1266 responses:
1267 '200':
1268 content:
1269 application/json:
1270 schema: { $ref: '#/components/schemas/FlowExecuteAutomatableResponse' }
1271
1272 /flows/{id}/runs/{run_id}/submit-review:
1273 post:
1274 tags: [Flows]
1275 summary: Submit run outcome to review tray
1276 parameters:
1277 - name: id
1278 in: path
1279 required: true
1280 schema: { type: string }
1281 - name: run_id
1282 in: path
1283 required: true
1284 schema: { type: string }
1285 requestBody:
1286 required: true
1287 content:
1288 application/json:
1289 schema:
1290 type: object
1291 required: [intent]
1292 properties:
1293 intent: { type: string }
1294 responses:
1295 '200':
1296 content:
1297 application/json:
1298 schema: { $ref: '#/components/schemas/FlowRunSubmitReviewResponse' }
1299
1300 /flows/{id}/runs/{run_id}/consent:
1301 post:
1302 tags: [Flows]
1303 summary: Mint execution consent for automatable steps
1304 parameters:
1305 - name: id
1306 in: path
1307 required: true
1308 schema: { type: string }
1309 - name: run_id
1310 in: path
1311 required: true
1312 schema: { type: string }
1313 requestBody:
1314 required: true
1315 content:
1316 application/json:
1317 schema:
1318 type: object
1319 required: [allowed_lanes, cost_cap_units]
1320 properties:
1321 allowed_lanes: { type: array, items: { type: string } }
1322 cost_cap_units: { type: integer }
1323 ttl_seconds: { type: integer }
1324 responses:
1325 '201':
1326 content:
1327 application/json:
1328 schema: { $ref: '#/components/schemas/FlowExecutionConsentMintResponse' }
1329
1330 /metadata-facets:
1331 get:
1332 tags: [Notes]
1333 summary: Body-free MetadataFacets hints for one note
1334 description: >
1335 Returns knowtation.metadata_facets/v0 metadata for one authorized vault-relative note.
1336 The response excludes note body text, snippets, full frontmatter, absolute paths,
1337 provider payloads, MCP resource URIs, summaries, labels, vectors, OCR, PageIndex output,
1338 media metadata, memory events, persistence records, sidecars, LLM calls, and write-back state.
1339 parameters:
1340 - name: path
1341 in: query
1342 required: true
1343 schema: { type: string }
1344 description: Vault-relative Markdown note path.
1345 responses:
1346 '200':
1347 content:
1348 application/json:
1349 schema: { $ref: '#/components/schemas/MetadataFacets' }
1350 '400':
1351 content:
1352 application/json:
1353 schema: { $ref: '#/components/schemas/Error' }
1354 '401':
1355 content:
1356 application/json:
1357 schema: { $ref: '#/components/schemas/Error' }
1358 '403':
1359 content:
1360 application/json:
1361 schema: { $ref: '#/components/schemas/Error' }
1362 '404':
1363 content:
1364 application/json:
1365 schema: { $ref: '#/components/schemas/Error' }
1366 '502':
1367 content:
1368 application/json:
1369 schema: { $ref: '#/components/schemas/Error' }
1370
1371 /section-source:
1372 get:
1373 tags: [Notes]
1374 summary: Body-free SectionSource metadata for one note
1375 description: >
1376 Returns knowtation.section_source/v0 metadata for one authorized vault-relative note.
1377 The response excludes note body text, section body text, snippets, full frontmatter,
1378 line ranges, byte offsets, section body lengths, absolute paths, raw canister payloads,
1379 provider payloads, and MCP resource URIs.
1380 parameters:
1381 - name: path
1382 in: query
1383 required: true
1384 schema: { type: string }
1385 description: Vault-relative Markdown note path.
1386 responses:
1387 '200':
1388 content:
1389 application/json:
1390 schema: { $ref: '#/components/schemas/SectionSource' }
1391 '400':
1392 content:
1393 application/json:
1394 schema: { $ref: '#/components/schemas/Error' }
1395 '401':
1396 content:
1397 application/json:
1398 schema: { $ref: '#/components/schemas/Error' }
1399 '403':
1400 content:
1401 application/json:
1402 schema: { $ref: '#/components/schemas/Error' }
1403 '404':
1404 content:
1405 application/json:
1406 schema: { $ref: '#/components/schemas/Error' }
1407 '502':
1408 content:
1409 application/json:
1410 schema: { $ref: '#/components/schemas/Error' }
1411
1412 /index:
1413 post:
1414 tags: [Notes]
1415 summary: Re-run indexer (vault to vector store)
1416 responses:
1417 '200':
1418 content:
1419 application/json:
1420 schema:
1421 type: object
1422 properties:
1423 ok: { type: boolean }
1424 notesProcessed: { type: integer }
1425 chunksIndexed: { type: integer }
1426 vectors_deleted: { type: integer, description: Rows removed for this vault before upsert (hosted sqlite-vec) }
1427 '500':
1428 content:
1429 application/json:
1430 schema: { $ref: '#/components/schemas/Error' }
1431
1432 /export:
1433 post:
1434 tags: [Notes]
1435 summary: Export one note to content (returns body + filename for client download)
1436 requestBody:
1437 required: true
1438 content:
1439 application/json:
1440 schema:
1441 type: object
1442 required: [path]
1443 properties:
1444 path: { type: string }
1445 format: { type: string, enum: [md, html] }
1446 responses:
1447 '200':
1448 content:
1449 application/json:
1450 schema:
1451 type: object
1452 properties:
1453 content: { type: string }
1454 filename: { type: string }
1455 '400':
1456 content:
1457 application/json:
1458 schema: { $ref: '#/components/schemas/Error' }
1459 '404':
1460 content:
1461 application/json:
1462 schema: { $ref: '#/components/schemas/Error' }
1463
1464 /import:
1465 post:
1466 tags: [Notes]
1467 summary: Import from uploaded file or ZIP (multipart: source_type; file except for google-sheets; optional project, tags, spreadsheet_id for google-sheets)
1468 requestBody:
1469 required: true
1470 content:
1471 multipart/form-data:
1472 schema:
1473 type: object
1474 required: [source_type]
1475 properties:
1476 source_type:
1477 type: string
1478 description: Importer id. For google-sheets, omit file and set spreadsheet_id; optional sheets_range (A1 notation). See lib/import-source-types.mjs.
1479 file: { type: string, format: binary, description: Required for all importers except google-sheets. }
1480 spreadsheet_id:
1481 type: string
1482 description: Required when source_type is google-sheets (id from the Google Sheets URL).
1483 sheets_range:
1484 type: string
1485 description: Optional for google-sheets; A1 range. Omit to read the first sheet from A1.
1486 project: { type: string }
1487 output_dir: { type: string }
1488 tags: { type: string }
1489 responses:
1490 '200':
1491 content:
1492 application/json:
1493 schema:
1494 type: object
1495 properties:
1496 imported: { type: array, items: { type: object } }
1497 count: { type: integer }
1498 '400':
1499 content:
1500 application/json:
1501 schema: { $ref: '#/components/schemas/Error' }
1502 '500':
1503 content:
1504 application/json:
1505 schema: { $ref: '#/components/schemas/Error' }
1506
1507 /import-url:
1508 post:
1509 tags: [Notes]
1510 summary: Import from a public https URL (JSON body; editor/admin)
1511 requestBody:
1512 required: true
1513 content:
1514 application/json:
1515 schema:
1516 type: object
1517 required: [url]
1518 properties:
1519 url: { type: string, description: 'Full https URL' }
1520 mode: { type: string, enum: [auto, bookmark, extract], description: 'Capture mode (default auto)' }
1521 project: { type: string }
1522 output_dir: { type: string }
1523 tags: { oneOf: [{ type: string }, { type: array, items: { type: string } }] }
1524 responses:
1525 '200':
1526 content:
1527 application/json:
1528 schema:
1529 type: object
1530 properties:
1531 imported: { type: array, items: { type: object } }
1532 count: { type: integer }
1533 '400':
1534 content:
1535 application/json:
1536 schema: { $ref: '#/components/schemas/Error' }
1537 '500':
1538 content:
1539 application/json:
1540 schema: { $ref: '#/components/schemas/Error' }
1541
1542 /settings:
1543 get:
1544 tags: [Notes]
1545 summary: Config status for Settings UI (no secrets)
1546 responses:
1547 '200':
1548 content:
1549 application/json:
1550 schema:
1551 type: object
1552 properties:
1553 vault_path_display: { type: string }
1554 vault_git:
1555 type: object
1556 properties:
1557 enabled: { type: boolean }
1558 has_remote: { type: boolean }
1559 auto_commit: { type: boolean }
1560 auto_push: { type: boolean }
1561
1562 /vault/sync:
1563 post:
1564 tags: [Notes]
1565 summary: Manual vault backup (git add, commit, push)
1566 description: Self-hosted runs local git. Hosted (bridge) pushes notes as Markdown plus `.knowtation/backup/v1/snapshot.json` with full proposals.
1567 responses:
1568 '200':
1569 content:
1570 application/json:
1571 schema:
1572 type: object
1573 properties:
1574 ok: { type: boolean }
1575 message: { type: string }
1576 notesCount: { type: integer, description: Hosted bridge only }
1577 proposalsCount: { type: integer, description: Hosted bridge only }
1578 '400':
1579 content:
1580 application/json:
1581 schema: { $ref: '#/components/schemas/Error' }
1582 '500':
1583 content:
1584 application/json:
1585 schema: { $ref: '#/components/schemas/Error' }
1586
1587 /search:
1588 post:
1589 tags: [Search]
1590 summary: Vault search (semantic or keyword)
1591 requestBody:
1592 required: true
1593 content:
1594 application/json:
1595 schema:
1596 type: object
1597 required: [query]
1598 properties:
1599 query: { type: string }
1600 mode: { type: string, enum: [semantic, keyword], description: Omitted or semantic = vector search; keyword = substring/token match on note text }
1601 match: { type: string, enum: [phrase, all_terms], description: Keyword only; phrase = full query substring; all_terms = every token must appear }
1602 folder: { type: string }
1603 project: { type: string }
1604 tag: { type: string }
1605 since: { type: string }
1606 until: { type: string }
1607 chain: { type: string }
1608 entity: { type: string }
1609 episode: { type: string }
1610 limit: { type: integer }
1611 order: { type: string }
1612 fields: { type: string }
1613 content_scope: { type: string, enum: [notes, approval_logs], description: Narrow to normal notes vs approvals/ logs }
1614 snippetChars: { type: integer }
1615 count_only: { type: boolean }
1616 countOnly: { type: boolean }
1617 responses:
1618 '200':
1619 content:
1620 application/json:
1621 schema:
1622 type: object
1623 properties:
1624 results: { type: array, items: { $ref: '#/components/schemas/SearchResult' } }
1625 query: { type: string }
1626 mode: { type: string, enum: [semantic, keyword] }
1627 count: { type: integer, description: Present when count_only keyword search }
1628 '400':
1629 content:
1630 application/json:
1631 schema: { $ref: '#/components/schemas/Error' }
1632
1633 /proposals:
1634 get:
1635 tags: [Proposals]
1636 summary: List proposals
1637 parameters:
1638 - name: status
1639 in: query
1640 schema: { type: string }
1641 - name: limit
1642 in: query
1643 schema: { type: integer }
1644 - name: offset
1645 in: query
1646 schema: { type: integer }
1647 - name: label
1648 in: query
1649 description: Match if proposal labels include this string (case-insensitive)
1650 schema: { type: string }
1651 - name: source
1652 in: query
1653 schema: { type: string }
1654 - name: path_prefix
1655 in: query
1656 schema: { type: string }
1657 - name: evaluation_status
1658 in: query
1659 description: Filter by evaluation_status (none, pending, passed, failed, needs_changes)
1660 schema: { type: string }
1661 - name: review_queue
1662 in: query
1663 description: Exact match on proposal review_queue
1664 schema: { type: string }
1665 - name: review_severity
1666 in: query
1667 description: standard or elevated
1668 schema: { type: string }
1669 responses:
1670 '200':
1671 content:
1672 application/json:
1673 schema:
1674 type: object
1675 properties:
1676 proposals: { type: array, items: { $ref: '#/components/schemas/Proposal' } }
1677 total: { type: integer }
1678 post:
1679 tags: [Proposals]
1680 summary: Create proposal
1681 requestBody:
1682 content:
1683 application/json:
1684 schema:
1685 type: object
1686 properties:
1687 path: { type: string }
1688 body: { type: string }
1689 frontmatter: { type: object }
1690 intent: { type: string }
1691 base_state_id: { type: string }
1692 external_ref: { type: string }
1693 labels: { type: array, items: { type: string } }
1694 source: { type: string }
1695 responses:
1696 '201':
1697 content:
1698 application/json:
1699 schema:
1700 type: object
1701 properties:
1702 proposal_id: { type: string }
1703 path: { type: string }
1704 status: { type: string, enum: [proposed] }
1705 '400':
1706
1707 /proposals/{id}:
1708 get:
1709 tags: [Proposals]
1710 summary: Get one proposal
1711 parameters:
1712 - name: id
1713 in: path
1714 required: true
1715 schema: { type: string }
1716 responses:
1717 '200':
1718 content:
1719 application/json:
1720 schema: { $ref: '#/components/schemas/ProposalDetail' }
1721 '404':
1722
1723 /proposals/{id}/review-hints:
1724 post:
1725 tags: [Proposals]
1726 summary: Store async LLM review hints (canister; not a merge gate)
1727 parameters:
1728 - name: id
1729 in: path
1730 required: true
1731 schema: { type: string }
1732 requestBody:
1733 content:
1734 application/json:
1735 schema:
1736 type: object
1737 properties:
1738 review_hints: { type: string }
1739 review_hints_model: { type: string }
1740 responses:
1741 '200':
1742 content:
1743 application/json:
1744 schema:
1745 type: object
1746 properties:
1747 proposal_id: { type: string }
1748 ok: { type: boolean }
1749
1750 /proposals/{id}/evaluation:
1751 post:
1752 tags: [Proposals]
1753 summary: Submit human evaluation (admin or evaluator)
1754 parameters:
1755 - name: id
1756 in: path
1757 required: true
1758 schema: { type: string }
1759 requestBody:
1760 content:
1761 application/json:
1762 schema:
1763 type: object
1764 required: [outcome]
1765 properties:
1766 outcome:
1767 type: string
1768 enum: [pass, fail, needs_changes]
1769 checklist:
1770 type: array
1771 items:
1772 type: object
1773 properties:
1774 id: { type: string }
1775 passed: { type: boolean }
1776 grade: { type: string }
1777 comment: { type: string }
1778 responses:
1779 '200':
1780 content:
1781 application/json:
1782 schema: { $ref: '#/components/schemas/ProposalDetail' }
1783 '400':
1784 '404':
1785
1786 /proposals/{id}/approve:
1787 post:
1788 tags: [Proposals]
1789 summary: Apply proposal to vault
1790 parameters:
1791 - name: id
1792 in: path
1793 required: true
1794 schema: { type: string }
1795 requestBody:
1796 content:
1797 application/json:
1798 schema:
1799 type: object
1800 properties:
1801 base_state_id: { type: string }
1802 waiver_reason:
1803 type: string
1804 description: Admin override when evaluation is not passed (min length 3 after trim)
1805 external_ref:
1806 type: string
1807 description: Optional cross-system lineage id (e.g. Muse); server may resolve via MUSE_URL when omitted
1808 responses:
1809 '200':
1810 content:
1811 application/json:
1812 schema:
1813 type: object
1814 properties:
1815 proposal_id: { type: string }
1816 status: { type: string, enum: [approved] }
1817 external_ref: { type: string }
1818 '403':
1819 description: EVALUATION_REQUIRED — pass evaluation or provide waiver_reason
1820 '409':
1821 description: base_state_id mismatch (CONFLICT)
1822
1823 /proposals/{id}/enrich:
1824 post:
1825 tags: [Proposals]
1826 summary: Optional LLM summary and suggested labels (KNOWTATION_HUB_PROPOSAL_ENRICH=1)
1827 parameters:
1828 - name: id
1829 in: path
1830 required: true
1831 schema: { type: string }
1832 responses:
1833 '200':
1834 content:
1835 application/json:
1836 schema: { $ref: '#/components/schemas/ProposalDetail' }
1837 '400':
1838 description: >-
1839 ICP canister — suggested_labels_json or assistant_suggested_frontmatter_json is valid JSON
1840 but exceeds max length (4000 / 14000 characters) after validation.
1841 '404':
1842
1843 /proposals/{id}/discard:
1844 post:
1845 tags: [Proposals]
1846 summary: Discard proposal
1847 parameters:
1848 - name: id
1849 in: path
1850 required: true
1851 schema: { type: string }
1852 responses:
1853 '200':
1854 content:
1855 application/json:
1856 schema:
1857 type: object
1858 properties:
1859 proposal_id: { type: string }
1860 status: { type: string, enum: [discarded] }
1861
1862 /capture:
1863 post:
1864 tags: [Capture]
1865 summary: Ingest message into vault inbox (webhook-style)
1866 description: Same contract as capture-webhook. If CAPTURE_WEBHOOK_SECRET is set, require X-Webhook-Secret header.
1867 security: []
1868 requestBody:
1869 content:
1870 application/json:
1871 schema:
1872 type: object
1873 required: [body]
1874 properties:
1875 body: { type: string }
1876 source_id: { type: string }
1877 source: { type: string }
1878 project: { type: string }
1879 tags: { type: array, items: { type: string } }
1880 responses:
1881 '200':
1882 content:
1883 application/json:
1884 schema: { type: object, properties: { ok: { type: boolean }, path: { type: string } } }
1885 '400':
1886
1887 components:
1888 securitySchemes:
1889 BearerAuth:
1890 type: http
1891 scheme: bearer
1892 bearerFormat: JWT
1893
1894 schemas:
1895 Error:
1896 type: object
1897 properties:
1898 error: { type: string }
1899 code: { type: string }
1900
1901 NoteListItem:
1902 type: object
1903 properties:
1904 path: { type: string }
1905 title: { type: string, nullable: true }
1906 project: { type: string, nullable: true }
1907 tags: { type: array, items: { type: string } }
1908 date: { type: string, nullable: true }
1909
1910 NoteFull:
1911 type: object
1912 properties:
1913 path: { type: string }
1914 frontmatter: { type: object }
1915 body: { type: string }
1916
1917 SearchResult:
1918 type: object
1919 properties:
1920 path: { type: string }
1921 snippet: { type: string }
1922 score: { type: number }
1923 project: { type: string }
1924 tags: { type: array, items: { type: string } }
1925
1926 NoteOutline:
1927 type: object
1928 required: [schema, path, headings, truncated]
1929 properties:
1930 schema:
1931 type: string
1932 enum: [knowtation.note_outline/v1]
1933 path: { type: string }
1934 title: { type: string, nullable: true }
1935 headings:
1936 type: array
1937 maxItems: 500
1938 items: { $ref: '#/components/schemas/NoteOutlineHeading' }
1939 truncated: { type: boolean }
1940
1941 NoteOutlineHeading:
1942 type: object
1943 required: [level, text, id]
1944 properties:
1945 level: { type: integer, minimum: 1, maximum: 6 }
1946 text: { type: string }
1947 id: { type: string }
1948
1949 DocumentTree:
1950 type: object
1951 required: [schema, path, root, truncated]
1952 properties:
1953 schema:
1954 type: string
1955 enum: [knowtation.document_tree/v0]
1956 path: { type: string }
1957 title: { type: string, nullable: true }
1958 root:
1959 type: object
1960 required: [children]
1961 properties:
1962 children:
1963 type: array
1964 maxItems: 500
1965 items: { $ref: '#/components/schemas/DocumentTreeNode' }
1966 truncated: { type: boolean }
1967
1968 DocumentTreeNode:
1969 type: object
1970 required: [id, level, text, children]
1971 properties:
1972 id: { type: string }
1973 level: { type: integer, minimum: 1, maximum: 6 }
1974 text: { type: string }
1975 children:
1976 type: array
1977 items: { $ref: '#/components/schemas/DocumentTreeNode' }
1978
1979 MetadataFacets:
1980 type: object
1981 required: [schema, path, facets, inferred, truncated]
1982 properties:
1983 schema:
1984 type: string
1985 enum: [knowtation.metadata_facets/v0]
1986 path: { type: string }
1987 facets:
1988 type: object
1989 required: [project, tags, date, updated, causal_chain_id, entity, episode_id]
1990 properties:
1991 project: { type: string, nullable: true }
1992 tags:
1993 type: array
1994 maxItems: 100
1995 items: { type: string }
1996 date: { type: string, nullable: true }
1997 updated: { type: string, nullable: true }
1998 causal_chain_id: { type: string, nullable: true }
1999 entity:
2000 type: array
2001 maxItems: 100
2002 items: { type: string }
2003 episode_id: { type: string, nullable: true }
2004 inferred:
2005 type: object
2006 required: [folder, source_type]
2007 properties:
2008 folder: { type: string, nullable: true }
2009 source_type: { nullable: true, enum: [null] }
2010 truncated: { type: boolean }
2011
2012 SectionSource:
2013 type: object
2014 required: [schema, path, sections, truncated]
2015 properties:
2016 schema:
2017 type: string
2018 enum: [knowtation.section_source/v0]
2019 path: { type: string }
2020 title: { type: string, nullable: true }
2021 sections:
2022 type: array
2023 items: { $ref: '#/components/schemas/SectionSourceSection' }
2024 truncated: { type: boolean }
2025
2026 SectionSourceSection:
2027 type: object
2028 required:
2029 - section_id
2030 - heading_id
2031 - level
2032 - heading_path
2033 - heading_text
2034 - child_section_ids
2035 - body_available
2036 - body_returned
2037 - snippet_returned
2038 properties:
2039 section_id: { type: string }
2040 heading_id: { type: string }
2041 level: { type: integer, minimum: 1, maximum: 6 }
2042 heading_path: { type: array, items: { type: string } }
2043 heading_text: { type: string }
2044 child_section_ids: { type: array, items: { type: string } }
2045 body_available: { type: boolean }
2046 body_returned: { type: boolean, enum: [false] }
2047 snippet_returned: { type: boolean, enum: [false] }
2048
2049 Proposal:
2050 type: object
2051 properties:
2052 proposal_id: { type: string }
2053 path: { type: string }
2054 status: { type: string }
2055 intent: { type: string }
2056 base_state_id: { type: string }
2057 external_ref: { type: string }
2058 vault_id: { type: string }
2059 proposed_by: { type: string }
2060 labels: { type: array, items: { type: string } }
2061 source: { type: string }
2062 suggested_labels: { type: array, items: { type: string } }
2063 assistant_notes: { type: string }
2064 assistant_model: { type: string }
2065 assistant_at: { type: string }
2066 created_at: { type: string }
2067 updated_at: { type: string }
2068 evaluation_status:
2069 type: string
2070 enum: [none, pending, passed, failed, needs_changes]
2071 evaluation_grade: { type: string }
2072 evaluation_comment: { type: string }
2073 evaluated_by: { type: string }
2074 evaluated_at: { type: string }
2075 evaluation_waiver:
2076 type: object
2077 nullable: true
2078 properties:
2079 by: { type: string }
2080 at: { type: string }
2081 reason: { type: string }
2082 review_queue: { type: string }
2083 review_severity: { type: string, enum: [standard, elevated] }
2084 auto_flag_reasons:
2085 type: array
2086 items: { type: string }
2087 auto_flag_reasons_json: { type: string, description: JSON array string on canister }
2088 review_hints: { type: string }
2089 review_hints_at: { type: string }
2090 review_hints_model: { type: string }
2091 assistant_suggested_frontmatter:
2092 type: object
2093 description: Normalized SPEC-aligned suggested note metadata from Enrich (object on GET); omitted or empty on older proposals
2094 additionalProperties: true
2095
2096 ProposalDetail:
2097 allOf:
2098 - { $ref: '#/components/schemas/Proposal' }
2099 - type: object
2100 properties:
2101 body: { type: string }
2102 frontmatter: { type: object }
2103 evaluation_checklist:
2104 type: array
2105 items:
2106 type: object
2107 properties:
2108 id: { type: string }
2109 label: { type: string }
2110 passed: { type: boolean }
2111
2112 CalendarTimeline:
2113 type: object
2114 required: [schema, vault_id, from, to, layers, items]
2115 properties:
2116 schema:
2117 type: string
2118 enum: [knowtation.calendar_timeline/v0]
2119 vault_id: { type: string }
2120 from: { type: string }
2121 to: { type: string }
2122 layers:
2123 type: array
2124 items:
2125 type: string
2126 enum: [notes, events]
2127 items:
2128 type: array
2129 items:
2130 oneOf:
2131 - { $ref: '#/components/schemas/CalendarTimelineNoteItem' }
2132 - { $ref: '#/components/schemas/CalendarTimelineEventItem' }
2133
2134 CalendarTimelineNoteItem:
2135 type: object
2136 required: [kind, date, path, title, project, tags, sort_at]
2137 properties:
2138 kind:
2139 type: string
2140 enum: [note]
2141 date: { type: string }
2142 path: { type: string }
2143 title: { type: string, nullable: true }
2144 project: { type: string, nullable: true }
2145 tags:
2146 type: array
2147 items: { type: string }
2148 sort_at: { type: string }
2149
2150 CalendarTimelineEventItem:
2151 type: object
2152 required: [kind, event_id, source_calendar_id, start, end, timezone, summary, busy, status, calendar_label, sort_at]
2153 properties:
2154 kind:
2155 type: string
2156 enum: [event]
2157 event_id: { type: string }
2158 source_calendar_id: { type: string }
2159 start: { type: string }
2160 end: { type: string }
2161 timezone: { type: string }
2162 summary: { type: string, nullable: true }
2163 busy: { type: boolean }
2164 status:
2165 type: string
2166 enum: [confirmed, cancelled, tentative]
2167 calendar_label: { type: string, nullable: true }
2168 sort_at: { type: string }
2169
2170 CalendarAgentContext:
2171 type: object
2172 required: [schema, vault_id, from, to, requested_tier, effective_tier, policy_agent_context_tier_max_cap, source_calendars, items]
2173 properties:
2174 schema:
2175 type: string
2176 enum: [knowtation.calendar_agent_context/v0]
2177 vault_id: { type: string }
2178 from: { type: string }
2179 to: { type: string }
2180 requested_tier:
2181 type: integer
2182 minimum: 0
2183 maximum: 2
2184 effective_tier:
2185 type: integer
2186 minimum: 0
2187 maximum: 2
2188 description: Requested tier after the org policy cap is applied.
2189 policy_agent_context_tier_max_cap:
2190 type: integer
2191 minimum: 0
2192 maximum: 4
2193 source_calendars:
2194 type: array
2195 items: { $ref: '#/components/schemas/AgentContextCalendarSummary' }
2196 items:
2197 type: array
2198 items: { $ref: '#/components/schemas/CalendarAgentContextEventItem' }
2199
2200 AgentContextCalendarSummary:
2201 type: object
2202 required: [source_calendar_id, display_name, user_group, enabled_for_agents, agent_context_tier_max, effective_tier, event_count]
2203 properties:
2204 source_calendar_id: { type: string }
2205 display_name: { type: string }
2206 user_group:
2207 type: string
2208 nullable: true
2209 enum: [personal, work, school, other, null]
2210 enabled_for_agents: { type: boolean }
2211 agent_context_tier_max:
2212 type: integer
2213 minimum: 0
2214 maximum: 4
2215 effective_tier:
2216 type: integer
2217 minimum: 0
2218 maximum: 2
2219 event_count: { type: integer }
2220
2221 CalendarAgentContextEventItem:
2222 type: object
2223 required: [event_id, source_calendar_id, external_uid, start, end, timezone, busy, status, agent_tier]
2224 description: >
2225 Redacted event. `summary` and `calendar_label` are present only at tier 2;
2226 tier 1 omits the event title entirely.
2227 properties:
2228 event_id: { type: string }
2229 source_calendar_id: { type: string }
2230 external_uid: { type: string }
2231 start: { type: string }
2232 end: { type: string }
2233 timezone: { type: string }
2234 busy: { type: boolean }
2235 status:
2236 type: string
2237 enum: [confirmed, cancelled, tentative]
2238 agent_tier:
2239 type: integer
2240 minimum: 1
2241 maximum: 2
2242 summary: { type: string, nullable: true }
2243 calendar_label: { type: string, nullable: true }
2244
2245 SourceCalendarList:
2246 type: object
2247 required: [schema, vault_id, source_calendars]
2248 properties:
2249 schema:
2250 type: string
2251 enum: [knowtation.source_calendars/v0]
2252 vault_id: { type: string }
2253 source_calendars:
2254 type: array
2255 items: { $ref: '#/components/schemas/SourceCalendar' }
2256
2257 SourceCalendar:
2258 type: object
2259 required: [source_calendar_id, connector_id, display_name, enabled_for_sync, enabled_for_display, enabled_for_agents, agent_context_tier_max]
2260 properties:
2261 source_calendar_id: { type: string }
2262 connector_id: { type: string }
2263 display_name: { type: string }
2264 color: { type: string, nullable: true }
2265 user_group:
2266 type: string
2267 nullable: true
2268 enum: [personal, work, school, other, null]
2269 enabled_for_sync: { type: boolean }
2270 enabled_for_display: { type: boolean }
2271 enabled_for_agents: { type: boolean }
2272 agent_context_tier_max:
2273 type: integer
2274 minimum: 0
2275 maximum: 4
2276 provider: { type: string }
2277
2278 CalendarIcsImportRequest:
2279 type: object
2280 required: [ics_text]
2281 properties:
2282 ics_text: { type: string }
2283 display_name: { type: string }
2284 source_calendar_id: { type: string }
2285 connector_id: { type: string }
2286 default_timezone: { type: string }
2287
2288 CalendarIcsImportResult:
2289 type: object
2290 required: [schema, vault_id, source_calendar_id, connector_id, imported, updated]
2291 properties:
2292 schema:
2293 type: string
2294 enum: [knowtation.calendar_import/v0]
2295 vault_id: { type: string }
2296 source_calendar_id: { type: string }
2297 connector_id: { type: string }
2298 imported: { type: integer }
2299 updated: { type: integer }
2300
2301 SourceCalendarPatchRequest:
2302 type: object
2303 minProperties: 1
2304 properties:
2305 enabled_for_display: { type: boolean }
2306 enabled_for_agents: { type: boolean }
2307 agent_context_tier_max:
2308 type: integer
2309 minimum: 0
2310 maximum: 4
2311 user_group:
2312 type: string
2313 nullable: true
2314 enum: [personal, work, school, other, null]
2315
2316 SourceCalendarPatchResult:
2317 type: object
2318 required: [schema, vault_id, policy_agent_context_tier_max_cap, source_calendar]
2319 properties:
2320 schema:
2321 type: string
2322 enum: [knowtation.source_calendar_patch/v0]
2323 vault_id: { type: string }
2324 policy_agent_context_tier_max_cap:
2325 type: integer
2326 minimum: 0
2327 maximum: 4
2328 source_calendar: { $ref: '#/components/schemas/SourceCalendar' }
2329
2330 FlowListResponse:
2331 type: object
2332 required: [schema, vault_id, effective_scope, flows, truncated]
2333 properties:
2334 schema:
2335 type: string
2336 enum: [knowtation.flow_list/v0]
2337 vault_id: { type: string }
2338 effective_scope:
2339 type: string
2340 enum: [personal, project, org]
2341 flows:
2342 type: array
2343 maxItems: 200
2344 items: { $ref: '#/components/schemas/FlowSummary' }
2345 truncated: { type: boolean }
2346
2347 FlowSummary:
2348 type: object
2349 required: [schema, flow_id, title, version, scope, summary, tags, step_count, updated, truncated]
2350 properties:
2351 schema:
2352 type: string
2353 enum: [knowtation.flow/v0]
2354 flow_id: { type: string }
2355 title: { type: string }
2356 version: { type: string }
2357 scope:
2358 type: string
2359 enum: [personal, project, org]
2360 summary: { type: string }
2361 tags:
2362 type: array
2363 maxItems: 32
2364 items: { type: string }
2365 step_count: { type: integer, minimum: 0 }
2366 updated: { type: string }
2367 truncated: { type: boolean }
2368
2369 FlowGetResponse:
2370 type: object
2371 required: [schema, vault_id, flow, steps]
2372 properties:
2373 schema:
2374 type: string
2375 enum: [knowtation.flow_get/v0]
2376 vault_id: { type: string }
2377 flow: { $ref: '#/components/schemas/Flow' }
2378 steps:
2379 type: array
2380 maxItems: 100
2381 items: { $ref: '#/components/schemas/FlowStep' }
2382
2383 FlowProposeRequest:
2384 type: object
2385 required: [flow, steps, intent]
2386 description: Propose a new Flow. intent is untrusted and recorded verbatim.
2387 properties:
2388 flow: { $ref: '#/components/schemas/Flow' }
2389 steps:
2390 type: array
2391 maxItems: 100
2392 items: { $ref: '#/components/schemas/FlowStep' }
2393 intent: { type: string, minLength: 1 }
2394
2395 FlowProposeEditRequest:
2396 type: object
2397 required: [flow, steps, intent, base_version, base_state_id]
2398 description: >
2399 Propose an edit. base_version + base_state_id (flowst1_ token) gate
2400 optimistic concurrency; flow.version must exceed base_version.
2401 properties:
2402 flow: { $ref: '#/components/schemas/Flow' }
2403 steps:
2404 type: array
2405 maxItems: 100
2406 items: { $ref: '#/components/schemas/FlowStep' }
2407 intent: { type: string, minLength: 1 }
2408 base_version: { type: string }
2409 base_state_id: { type: string }
2410
2411 FlowImportRequest:
2412 type: object
2413 required: [bundle, intent]
2414 description: Import a portable bundle through the same scope-checked propose path.
2415 properties:
2416 bundle:
2417 type: object
2418 required: [flow, steps]
2419 properties:
2420 flow: { $ref: '#/components/schemas/Flow' }
2421 steps:
2422 type: array
2423 maxItems: 100
2424 items: { $ref: '#/components/schemas/FlowStep' }
2425 intent: { type: string, minLength: 1 }
2426 external_ref: { type: string }
2427 source_vault_hint: { type: string }
2428
2429 FlowProposalResponse:
2430 type: object
2431 required: [schema, proposal_id, flow_id, scope, auto_approvable, status, review_queue]
2432 description: >
2433 knowtation.flow_proposal/v0 envelope — pointers/labels only, never a
2434 rendered Flow body or secret. base_version/base_state_id are null for new.
2435 properties:
2436 schema:
2437 type: string
2438 enum: [knowtation.flow_proposal/v0]
2439 proposal_id: { type: string }
2440 flow_id: { type: string }
2441 base_version: { type: string, nullable: true }
2442 base_state_id: { type: string, nullable: true }
2443 scope:
2444 type: string
2445 enum: [personal, project, org]
2446 auto_approvable: { type: boolean }
2447 status:
2448 type: string
2449 enum: [proposed]
2450 review_queue: { type: string }
2451
2452 FlowExternalGrantMintRequest:
2453 type: object
2454 required: [flow_version, requested_tools]
2455 properties:
2456 flow_version: { type: string }
2457 requested_tools:
2458 type: array
2459 minItems: 1
2460 items: { type: string }
2461 ttl_seconds: { type: integer, minimum: 1 }
2462 actor_label: { type: string }
2463
2464 FlowExternalGrant:
2465 type: object
2466 required:
2467 - schema
2468 - grant_id
2469 - vault_id
2470 - scope
2471 - flow_id
2472 - flow_version
2473 - allowed_tools
2474 - allowed_harnesses
2475 - expires_at
2476 - issued_at
2477 - revoked_at
2478 - actor_hash
2479 - invocation_count
2480 properties:
2481 schema:
2482 type: string
2483 enum: [knowtation.flow_external_grant/v0]
2484 grant_id: { type: string }
2485 vault_id: { type: string }
2486 scope:
2487 type: string
2488 enum: [personal, project, org]
2489 flow_id: { type: string }
2490 flow_version: { type: string }
2491 allowed_tools:
2492 type: array
2493 items: { type: string }
2494 allowed_harnesses:
2495 type: array
2496 items: { type: string }
2497 expires_at: { type: string, format: date-time }
2498 issued_at: { type: string, format: date-time }
2499 revoked_at: { type: string, format: date-time, nullable: true }
2500 actor_hash: { type: string }
2501 max_invocations: { type: integer }
2502 invocation_count: { type: integer }
2503
2504 FlowExternalGrantMintResponse:
2505 type: object
2506 required: [schema, grant, bearer, expires_at]
2507 properties:
2508 schema:
2509 type: string
2510 enum: [knowtation.flow_external_grant_mint/v0]
2511 grant: { $ref: '#/components/schemas/FlowExternalGrant' }
2512 bearer: { type: string }
2513 expires_at: { type: string, format: date-time }
2514
2515 FlowExternalGrantListResponse:
2516 type: object
2517 required: [schema, vault_id, grants]
2518 properties:
2519 schema:
2520 type: string
2521 enum: [knowtation.flow_external_grant_list/v0]
2522 vault_id: { type: string }
2523 grants:
2524 type: array
2525 items: { $ref: '#/components/schemas/FlowExternalGrant' }
2526
2527 AgentIdentityRegisterRequest:
2528 type: object
2529 required: [kind]
2530 properties:
2531 kind:
2532 type: string
2533 enum: [user_owned, org_owned, delegate]
2534 agent_id: { type: string }
2535 label: { type: string }
2536 scope_ceiling:
2537 type: string
2538 enum: [personal, project, org]
2539
2540 DelegationProposalResponse:
2541 type: object
2542 required: [schema, proposal_id, intent]
2543 properties:
2544 schema:
2545 type: string
2546 enum: [knowtation.delegation_proposal/v0]
2547 proposal_id: { type: string }
2548 intent: { type: string }
2549 agent_id: { type: string }
2550 consent_id: { type: string }
2551
2552 AgentIdentity:
2553 type: object
2554 required:
2555 - schema
2556 - agent_id
2557 - kind
2558 - owner_ref
2559 - vault_id
2560 - scope_ceiling
2561 - status
2562 - created
2563 - updated
2564 properties:
2565 schema:
2566 type: string
2567 enum: [knowtation.agent_identity/v0]
2568 agent_id: { type: string }
2569 kind:
2570 type: string
2571 enum: [user_owned, org_owned, delegate]
2572 owner_ref: { type: string }
2573 vault_id: { type: string }
2574 scope_ceiling:
2575 type: string
2576 enum: [personal, project, org]
2577 label: { type: string }
2578 status:
2579 type: string
2580 enum: [active, suspended, revoked]
2581 created: { type: string, format: date-time }
2582 updated: { type: string, format: date-time }
2583
2584 AgentIdentityListResponse:
2585 type: object
2586 required: [schema, vault_id, identities]
2587 properties:
2588 schema:
2589 type: string
2590 enum: [knowtation.agent_identity_list/v0]
2591 vault_id: { type: string }
2592 identities:
2593 type: array
2594 items: { $ref: '#/components/schemas/AgentIdentity' }
2595
2596 DelegationConsentProposeRequest:
2597 type: object
2598 required: [delegate_agent_id, scope]
2599 properties:
2600 delegate_agent_id: { type: string }
2601 scope:
2602 type: string
2603 enum: [personal, project, org]
2604 workspace_id: { type: string }
2605 allowed_flow_ids:
2606 type: array
2607 items: { type: string }
2608 allowed_task_kinds:
2609 type: array
2610 items: { type: string }
2611 allowed_task_ids:
2612 type: array
2613 items: { type: string }
2614 expires_at: { type: string, format: date-time }
2615
2616 DelegationConsentProposeResponse:
2617 type: object
2618 required: [schema, proposal_id, intent, consent_id]
2619 properties:
2620 schema:
2621 type: string
2622 enum: [knowtation.delegation_proposal/v0]
2623 proposal_id: { type: string }
2624 intent: { type: string }
2625 consent_id: { type: string }
2626 consent_preview: { $ref: '#/components/schemas/DelegationConsent' }
2627
2628 DelegationConsent:
2629 type: object
2630 required:
2631 - schema
2632 - consent_id
2633 - principal_ref
2634 - delegate_agent_id
2635 - scope
2636 - revoked_at
2637 - evidence_ref
2638 - created
2639 properties:
2640 schema:
2641 type: string
2642 enum: [knowtation.delegation_consent/v0]
2643 consent_id: { type: string }
2644 principal_ref: { type: string }
2645 delegate_agent_id: { type: string }
2646 scope:
2647 type: string
2648 enum: [personal, project, org]
2649 workspace_id: { type: string }
2650 allowed_flow_ids:
2651 type: array
2652 items: { type: string }
2653 allowed_task_kinds:
2654 type: array
2655 items: { type: string }
2656 allowed_task_ids:
2657 type: array
2658 items: { type: string }
2659 expires_at: { type: string, format: date-time }
2660 revoked_at: { type: string, format: date-time, nullable: true }
2661 evidence_ref: { type: string }
2662 created: { type: string, format: date-time }
2663
2664 DelegationGrantMintRequest:
2665 type: object
2666 required: [consent_id, actor_agent_id]
2667 properties:
2668 consent_id: { type: string }
2669 actor_agent_id: { type: string }
2670 task_ref: { type: string }
2671 run_ref: { type: string }
2672 flow_id: { type: string }
2673 flow_version: { type: string }
2674 ttl_seconds: { type: integer, minimum: 1 }
2675
2676 DelegationGrant:
2677 type: object
2678 required:
2679 - schema
2680 - grant_id
2681 - consent_id
2682 - actor_agent_id
2683 - principal_ref
2684 - scope
2685 - expires_at
2686 - revoked_at
2687 - action_count
2688 - issued_at
2689 properties:
2690 schema:
2691 type: string
2692 enum: [knowtation.delegation_grant/v0]
2693 grant_id: { type: string }
2694 consent_id: { type: string }
2695 actor_agent_id: { type: string }
2696 principal_ref: { type: string }
2697 scope:
2698 type: string
2699 enum: [personal, project, org]
2700 workspace_id: { type: string }
2701 task_ref: { type: string }
2702 run_ref: { type: string }
2703 flow_id: { type: string }
2704 flow_version: { type: string }
2705 expires_at: { type: string, format: date-time }
2706 revoked_at: { type: string, format: date-time, nullable: true }
2707 max_actions: { type: integer }
2708 action_count: { type: integer }
2709 issued_at: { type: string, format: date-time }
2710
2711 DelegationGrantMintResponse:
2712 type: object
2713 required: [schema, grant, bearer, expires_at]
2714 properties:
2715 schema:
2716 type: string
2717 enum: [knowtation.delegation_grant_mint/v0]
2718 grant: { $ref: '#/components/schemas/DelegationGrant' }
2719 bearer: { type: string }
2720 expires_at: { type: string, format: date-time }
2721
2722 DelegationGrantListResponse:
2723 type: object
2724 required: [schema, vault_id, grants]
2725 properties:
2726 schema:
2727 type: string
2728 enum: [knowtation.delegation_grant_list/v0]
2729 vault_id: { type: string }
2730 grants:
2731 type: array
2732 items: { $ref: '#/components/schemas/DelegationGrant' }
2733
2734 DelegationAuditAppendRequest:
2735 type: object
2736 required: [grant_id, actor_agent_id, action, evidence_refs]
2737 properties:
2738 grant_id: { type: string }
2739 actor_agent_id: { type: string }
2740 principal_ref: { type: string }
2741 action:
2742 type: string
2743 enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]
2744 evidence_refs:
2745 type: array
2746 minItems: 1
2747 items: { type: string }
2748 task_ref: { type: string }
2749 run_ref: { type: string }
2750 flow_id: { type: string }
2751 flow_version: { type: string }
2752 step_id: { type: string }
2753 execution_location:
2754 type: string
2755 enum: [local, hosted, hybrid]
2756
2757 DelegationAudit:
2758 type: object
2759 required:
2760 - schema
2761 - audit_id
2762 - grant_id
2763 - actor_agent_id
2764 - principal_ref
2765 - action
2766 - evidence_refs
2767 - occurred_at
2768 properties:
2769 schema:
2770 type: string
2771 enum: [knowtation.delegation_audit/v0]
2772 audit_id: { type: string }
2773 grant_id: { type: string }
2774 actor_agent_id: { type: string }
2775 principal_ref: { type: string }
2776 task_ref: { type: string }
2777 run_ref: { type: string }
2778 flow_id: { type: string }
2779 flow_version: { type: string }
2780 step_id: { type: string }
2781 action:
2782 type: string
2783 enum: [advance_step, complete_task, propose_outcome, invoke_tool, mint_subgrant]
2784 evidence_refs:
2785 type: array
2786 items: { type: string }
2787 occurred_at: { type: string, format: date-time }
2788 execution_location:
2789 type: string
2790 enum: [local, hosted, hybrid]
2791
2792 FlowProjectResponse:
2793 type: object
2794 required: [schema, vault_id, projection, staleness, generator]
2795 properties:
2796 schema:
2797 type: string
2798 enum: [knowtation.flow_project/v0]
2799 vault_id: { type: string }
2800 projection: { $ref: '#/components/schemas/FlowProjection' }
2801 staleness: { $ref: '#/components/schemas/FlowProjectionStaleness' }
2802 generator: { $ref: '#/components/schemas/FlowProjectionGenerator' }
2803
2804 FlowProjection:
2805 type: object
2806 required: [schema, flow_id, flow_version, harness, rendered, generated_from_canonical, editable]
2807 properties:
2808 schema:
2809 type: string
2810 enum: [knowtation.flow_projection/v0]
2811 flow_id: { type: string }
2812 flow_version: { type: string }
2813 harness:
2814 type: string
2815 enum: [cursor_rule, cursor_skill, mcp_prompt, cli_runbook, agent_bundle]
2816 rendered:
2817 type: string
2818 maxLength: 65536
2819 generated_from_canonical:
2820 type: boolean
2821 enum: [true]
2822 editable:
2823 type: boolean
2824 enum: [false]
2825 fidelity:
2826 type: object
2827 required: [dropped_fields]
2828 properties:
2829 dropped_fields:
2830 type: array
2831 items: { type: string }
2832 notes: { type: string }
2833
2834 FlowProjectionStaleness:
2835 type: object
2836 required: [stale, projection_version, latest_version]
2837 properties:
2838 stale: { type: boolean }
2839 projection_version: { type: string }
2840 latest_version: { type: string }
2841
2842 FlowProjectionGenerator:
2843 type: object
2844 required: [generator_version, content_hash, generated_at]
2845 properties:
2846 generator_version: { type: string }
2847 content_hash: { type: string }
2848 generated_at: { type: string }
2849
2850 Flow:
2851 type: object
2852 required: [schema, flow_id, title, version, scope, summary, steps, updated, truncated]
2853 properties:
2854 schema:
2855 type: string
2856 enum: [knowtation.flow/v0]
2857 flow_id: { type: string }
2858 title: { type: string }
2859 version: { type: string }
2860 scope:
2861 type: string
2862 enum: [personal, project, org]
2863 summary: { type: string }
2864 tags:
2865 type: array
2866 maxItems: 32
2867 items: { type: string }
2868 steps:
2869 type: array
2870 maxItems: 100
2871 items: { type: string }
2872 inputs:
2873 type: array
2874 items:
2875 type: object
2876 required: [name, type, required]
2877 properties:
2878 name: { type: string }
2879 type: { type: string }
2880 required: { type: boolean }
2881 vault_mirror_path: { type: string, nullable: true }
2882 updated: { type: string }
2883 truncated: { type: boolean }
2884
2885 FlowStep:
2886 type: object
2887 required: [schema, step_id, flow_id, ordinal, owned_job, instruction, trigger, when_not_to_run, boundaries, output_shape, verification, automatable]
2888 properties:
2889 schema:
2890 type: string
2891 enum: [knowtation.flow_step/v0]
2892 step_id: { type: string }
2893 flow_id: { type: string }
2894 ordinal: { type: integer, minimum: 1 }
2895 owned_job: { type: string }
2896 instruction: { type: string }
2897 trigger: { type: string }
2898 when_not_to_run: { type: string }
2899 requires:
2900 type: array
2901 items:
2902 type: object
2903 required: [kind, id]
2904 properties:
2905 kind:
2906 type: string
2907 enum: [vault_scope, tool, file, artifact]
2908 id: { type: string }
2909 boundaries:
2910 type: array
2911 items: { type: string }
2912 skill_refs:
2913 type: array
2914 items:
2915 type: object
2916 required: [kind, id]
2917 properties:
2918 kind:
2919 type: string
2920 enum: [mcp_prompt, skill_pack, cli, external_tool]
2921 id: { type: string }
2922 inputs:
2923 type: array
2924 items:
2925 type: object
2926 required: [name, from]
2927 properties:
2928 name: { type: string }
2929 from: { type: string }
2930 outputs:
2931 type: array
2932 items:
2933 type: object
2934 required: [name, type]
2935 properties:
2936 name: { type: string }
2937 type: { type: string }
2938 output_shape: { type: string }
2939 verification:
2940 type: object
2941 required: [kind, evidence_required, description]
2942 properties:
2943 kind:
2944 type: string
2945 enum: [human_review, artifact_exists, value_match, test_pass, agent_check]
2946 evidence_required: { type: boolean }
2947 description: { type: string }
2948 automatable:
2949 type: string
2950 enum: [manual, agent_assisted, automatable]
File History 1 commit
sha256:0279cd72f3b5db53d740fb647a4b0bf68d2c327a0d05cbcb6234c2b128d57c11 feat(delegation): implement 7C-6 agent identity/delegation … Human minor ⚠ 33 days ago