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